diff --git a/docs/api/howtos/change-systemsoftware-version.mdx b/docs/api/howtos/change-systemsoftware-version.mdx index ec737b46..e80d6768 100644 --- a/docs/api/howtos/change-systemsoftware-version.mdx +++ b/docs/api/howtos/change-systemsoftware-version.mdx @@ -13,17 +13,17 @@ import OperationHint from "@site/src/components/OperationHint"; ## Prerequisites -This article assumes that you have already created an app installation and that you have the ID of that app installation. You can also use the `GET /v2/appinstallations/{appInstallationId}` endpoint to inspect the current configuration of said app installation. Relevant for this article is the `.systemSoftware` property, which is a map that contains the ID of the system software (as key) and the version that is currently installed. +This article assumes that you have already created an app installation and that you have the ID of that app installation. You can also use the endpoint to inspect the current configuration of said app installation. Relevant for this article is the `.systemSoftware` property, which is a map that contains the ID of the system software (as key) and the version that is currently installed. ## Determine the system software and version IDs -First, you need to determine the IDs of the system software and the version you want to change to. You can do this by calling the `GET /v2/systemsoftwares` endpoint and filtering the result set by the desired `.name` property. +First, you need to determine the IDs of the system software and the version you want to change to. You can do this by calling the endpoint and filtering the result set by the desired `.name` property. -Using that ID, you can then call the `GET /v2/systemsoftwares/{systemSoftwareId}/versions` endpoint to get a list of all available versions for that system software. To only select specific versions, you can use the `versionRange` query parameter. This parameter accepts any valid [semantic versioning constraint](https://devhints.io/semver), like `>= 14.0.0` or `^14.0.0`. +Using that ID, you can then call the endpoint to get a list of all available versions for that system software. To only select specific versions, you can use the `versionRange` query parameter. This parameter accepts any valid [semantic versioning constraint](https://devhints.io/semver), like `>= 14.0.0` or `^14.0.0`. ## Changing the system software version -To change the system software version, use the `PATCH /v2/appinstallations/{appinstallationId}` endpoint. You only need to provide the `.systemSoftware` property in the request body, which should contain the ID of the system software and the version you want to change to: +To change the system software version, use the . You only need to provide the `.systemSoftware` property in the request body, which should contain the ID of the system software and the version you want to change to: ``` PATCH /v2/appinstallations/{appInstallationId} HTTP/1.1 diff --git a/docs/api/howtos/create-nodejs.mdx b/docs/api/howtos/create-nodejs.mdx index 27ef3fc2..5895b001 100644 --- a/docs/api/howtos/create-nodejs.mdx +++ b/docs/api/howtos/create-nodejs.mdx @@ -8,6 +8,7 @@ tags: --- import OperationHint from "@site/src/components/OperationHint"; +import OperationLink from "@site/src/components/OperationLink"; ## Prerequisites @@ -20,18 +21,18 @@ To install a Node.js or Python application, you will need to have the following: Before installing a Node.js or Python application, you will need to determine the application ID and version ID of the generic custom Node.js (or Python, respectively) application. -For this, call the `/v2/apps` endpoint, and find the "Node.js" or "Python" application. These should have the following stable IDs: +For this, call the endpoint, and find the "Node.js" or "Python" application. These should have the following stable IDs: - Node.js: `3e7f920b-a711-4d2f-9871-661e1b41a2f0` - Python: `be57d166-dae9-4480-bae2-da3f3c6f0a2e` -Use the respective ID, depending on whether you want to install a Node.js or Python application. You can then use that ID to retrieve the recommended version to install for this app, by calling the `/v2/apps/{appID}/versions` endpoint. You can filter the returned versions by the `recommended` property. +Use the respective ID, depending on whether you want to install a Node.js or Python application. You can then use that ID to retrieve the recommended version to install for this app, by calling the endpoint. You can filter the returned versions by the `recommended` property. Please note that the actual version is rather inconsequential, as it refers only to the starter template used to create the application. The actual version of the application will be determined by your own code. ## Install the application -To deploy your application, you will need to call the `POST /v2/projects/{projectID}/appinstallations` endpoint. The relevant fields are the following: +To deploy your application, you will need to call the endpoint. The relevant fields are the following: - `appVersionId` needs to be the app version ID that you retrieved in the previous step. - `userInputs` needs to be an array of objects, each containing a `name` and `value` property. The allowed values for `name` are contained in the `userInputs` array of the app version object. In the case of Node.js, the only allowed value is `entrypoint`, which is the command that will be run to start your application. @@ -58,4 +59,4 @@ The response will contain the installation ID, that you can subsequently use to -To observe the installation status, you can call the `/v2/appinstallations/{installationID}` endpoint. Pay special attention to the `installationPath` field; this will contain the directory in your project file system that you should deploy your application to. +To observe the installation status, you can call the endpoint. Pay special attention to the `installationPath` field; this will contain the directory in your project file system that you should deploy your application to. diff --git a/docs/api/howtos/create-php.mdx b/docs/api/howtos/create-php.mdx index b2a87b72..0ebdb45c 100644 --- a/docs/api/howtos/create-php.mdx +++ b/docs/api/howtos/create-php.mdx @@ -7,6 +7,7 @@ tags: --- import OperationHint from "@site/src/components/OperationHint"; +import OperationLink from "@site/src/components/OperationLink"; ## Prerequisites @@ -19,13 +20,13 @@ To install a PHP application, you will need to have the following: Before installing a PHP application, you will need to determine the application ID and version ID of the generic custom PHP application. -For this, call the `/v2/apps` endpoint, and find the "PHP" application. It should have a stable ID of `34220303-cb87-4592-8a95-2eb20a97b2ac`. You can then use that ID to retrieve the recommended version to install for this app, by calling the `/v2/apps/{appID}/versions` endpoint. You can filter the returned versions by the `recommended` property. +For this, call the endpoint, and find the "PHP" application. It should have a stable ID of `34220303-cb87-4592-8a95-2eb20a97b2ac`. You can then use that ID to retrieve the recommended version to install for this app, by calling the endpoint. You can filter the returned versions by the `recommended` property. Please note that the actual version is rather inconsequential, as it refers only to the starter template used to create the application. The actual version of the application will be determined by your own code. ## Install the application -To deploy your application, you will need to call the `POST /v2/projects/{projectID}/appinstallations` endpoint. The relevant fields are the following: +To deploy your application, you will need to call the endpoint. The relevant fields are the following: - `appVersionId` needs to be the app version ID that you retrieved in the previous step. - `updatePolicy` needs to be set to `none`, as you will typically want to update your application by yourself. @@ -47,4 +48,4 @@ The response will contain the installation ID, that you can subsequently use to -To observe the installation status, you can call the `/v2/appinstallations/{installationID}` endpoint. Pay special attention to the `installationPath` field; this will contain the directory in your project file system that you should deploy your application to. +To observe the installation status, you can call the endpoint. Pay special attention to the `installationPath` field; this will contain the directory in your project file system that you should deploy your application to. diff --git a/docs/api/howtos/create-project.mdx b/docs/api/howtos/create-project.mdx index fb1e530a..6d65e95c 100644 --- a/docs/api/howtos/create-project.mdx +++ b/docs/api/howtos/create-project.mdx @@ -21,9 +21,9 @@ There are different ways to deploy a new project: ### …on a server -To create a project on an existing server, you will require that server’s ID. You can find all servers you have access to using the `GET /v2/servers` API endpoint. +To create a project on an existing server, you will require that server’s ID. You can find all servers you have access to using the endpoint. -To create a new project, send a `POST` request to the `/v2/placementgroups/{serverId}/projects` endpoint. The request body must contain a JSON object with the following properties: +To create a new project, send a request to the endpoint. The request body must contain a JSON object with the following properties: - `description` should contain a human-readable description of the project. This is a required value. @@ -31,7 +31,7 @@ The response, when successful, will contain a JSON object with the following pro - `id` is the ID of the newly created project. - + ### …as a stand-alone project @@ -43,7 +43,7 @@ Creating stand-alone projects is not supported, as of yet. ## Observing project readiness -A newly created project will not be available immediately (however, it should be available within a few seconds). To check whether a project is ready, send a `GET` request to the `/v2/projects/{projectID}` endpoint. Among other properties, the response will contain an `isReady` property. This property will be `true` when the project is ready, and `false` otherwise. +A newly created project will not be available immediately (however, it should be available within a few seconds). To check whether a project is ready, send a request to the endpoint. Among other properties, the response will contain an `isReady` property. This property will be `true` when the project is ready, and `false` otherwise. diff --git a/docs/api/howtos/create-redis.mdx b/docs/api/howtos/create-redis.mdx index 437de6b6..ab253faf 100644 --- a/docs/api/howtos/create-redis.mdx +++ b/docs/api/howtos/create-redis.mdx @@ -18,14 +18,14 @@ To create a Redis database, you will need to have access to a project. Refer to ## List available Redis versions -Set a `GET` request to the `/v2/redis-versions` endpoint to get a list of available Redis versions. (endpoint documentation for `database-list-redis-versions`) +Set a request to the endpoint to get a list of available Redis versions. ## Creating a Redis database -To create a Redis database, send a `POST` request to the `/v2/projects/{projectID}/redis-databases` endpoint. The request body must contain a JSON object with the following properties: +To create a Redis database, send a request to the endpoint. The request body must contain a JSON object with the following properties: - `description` should contain a human-readable description of the database. This is a required value. -- `version` should contain the version of the database. This is a required value, and must reference an existing version as returned by the `/v2/redis-versions` endpoint. +- `version` should contain the version of the database. This is a required value, and must reference an existing version as returned by the endpoint. The response will contain the following properties: @@ -35,7 +35,7 @@ The response will contain the following properties: ## Accessing the database -After creating a database, you can send a `GET` request to the `/v2/redis-databases/{id}` route. +After creating a database, you can send a request to the route. Among others, the response will contain the following values: diff --git a/docs/api/howtos/manage-mailbox.mdx b/docs/api/howtos/manage-mailbox.mdx index 2f2b2956..e355e467 100644 --- a/docs/api/howtos/manage-mailbox.mdx +++ b/docs/api/howtos/manage-mailbox.mdx @@ -8,6 +8,7 @@ tags: --- import OperationHint from "@site/src/components/OperationHint"; +import OperationLink from "@site/src/components/OperationLink"; import SchemaFromSpec from "@site/src/components/openapi/SchemaFromSpec"; ## Types of mailboxes @@ -23,7 +24,7 @@ To manage email accounts, you will need an existing project. You can create a ne ## Create a new email account -To create a new email account, send a `POST` request to the `/v2/projects/{projectID}/mailaddresses` endpoint. The request body must contain a JSON object with the following properties: +To create a new email account, send a request to the endpoint. The request body must contain a JSON object with the following properties: + ## Create a new forwarding address -A forwarding address is an email address that forwards all incoming emails to one or more other email addresses. To create a new forwarding address, send a `POST` request to the `/v2/projects/{projectID}/mailaddresses` endpoint. The request body must contain a JSON object with the following properties: +A forwarding address is an email address that forwards all incoming emails to one or more other email addresses. To create a new forwarding address, send a request to the endpoint. The request body must contain a JSON object with the following properties: endpoint. The request body must contain a JSON object with the following properties: - `description` (string, required): A description for the delivery box. This description will be displayed in the web interface. - `password` (string, required): The password for the delivery box. This password will be used to authenticate against the SMTP server. @@ -66,4 +67,6 @@ Take note of the password you set for the delivery box. You will not be able to ## Deleting email accounts -To delete an email address or a delivery box, send a `DELETE` request to the `/v2/mailaddresses/{id}` or `/v2/deliveryboxes/{id}` endpoint, respectively. The `id` parameter must contain the ID of the email address or delivery box you want to delete. No request body is needed. +To delete an email address or a delivery box, send a request to the or endpoint, respectively. The `id` parameter must contain the ID of the email address or delivery box you want to delete. No request body is needed. + + \ No newline at end of file diff --git a/docs/api/intro.md b/docs/api/intro.mdx similarity index 93% rename from docs/api/intro.md rename to docs/api/intro.mdx index 0502c0ac..7e86034e 100644 --- a/docs/api/intro.md +++ b/docs/api/intro.mdx @@ -5,6 +5,8 @@ description: | This page provides an introduction to the mStudio v2 API and its concepts. --- +import OperationLink from "@site/src/components/OperationLink"; + ## Base URLs The mStudio v2 API uses `https://api.mittwald.de/v2/` as base URL for all API endpoints. @@ -23,10 +25,10 @@ You can find the full API specification in the [OpenAPI 3.0 format](https://spec To authenticate to the API, you will need an **API Token**. You can obtain one either via the mittwald mStudio Web UI or via the API itself (if you already have another API token). 1. **In the UI**, go to your user profile and choose the [API tokens](https://studio.mittwald.de/app/profile/api-tokens) menu item. -2. Alternatively, **via the API**, use the `/v2/signup/token/api` endpoint. This requires you to already have an existing API token: +2. Alternatively, **via the API**, use the endpoint. This requires you to already have an existing API token: ```http - POST /v2/signup/token/api HTTP/1.1 + POST /v2/users/self/api-tokens HTTP/1.1 Host: api.mittwald.de Content-Type: application/json Authorization: Bearer diff --git a/i18n/de/code.json b/i18n/de/code.json index ec9380e7..0ca3b37e 100644 --- a/i18n/de/code.json +++ b/i18n/de/code.json @@ -340,6 +340,9 @@ "components.OperationHint.text": { "message": "Für Details siehe auch die Endpoint-Dokumentation für den folgenden API-Endpoint" }, + "components.OperationHint.text.plural": { + "message": "Für Details siehe auch die Endpoint-Dokumentationen für die folgenden API-Endpoints" + }, "theme.admonition.warning": { "message": "warnung", "description": "The default label used for the Warning admonition (:::warning)" @@ -450,5 +453,14 @@ }, "openapi.example": { "message": "Beispiel" + }, + "openapi.operation.metadata.deprecationnotice.text": { + "message": "This operation is deprecated and should not be used anymore. Please refer to this operation's description for alternatives." + }, + "components.OperationHint.heading.plural": { + "message": "components.OperationHint.heading.plural" + }, + "components.OperationHint.heading": { + "message": "components.OperationHint.heading" } } diff --git a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/change-systemsoftware-version.mdx b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/change-systemsoftware-version.mdx index 02d83331..cf3c2259 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/change-systemsoftware-version.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/change-systemsoftware-version.mdx @@ -13,17 +13,17 @@ import OperationHint from "@site/src/components/OperationHint"; ## Voraussetzungen -Dieser Artikel geht davon aus, dass du bereits eine App-Installation erstellt hast und die ID dieser App-Installation kennst. Du kannst auch den `GET /v2/appinstallations/{appInstallationId}`-Endpunkt verwenden, um die aktuelle Konfiguration dieser App-Installation zu inspizieren. Relevant für diesen Artikel ist die `.systemSoftware`-Eigenschaft; diese enthält eine Map, die die ID der Systemsoftware (als Schlüssel) und die aktuell installierte Version enthält. +Dieser Artikel geht davon aus, dass du bereits eine App-Installation erstellt hast und die ID dieser App-Installation kennst. Du kannst auch den -Endpunkt verwenden, um die aktuelle Konfiguration dieser App-Installation zu inspizieren. Relevant für diesen Artikel ist die `.systemSoftware`-Eigenschaft; diese enthält eine Map, die die ID der Systemsoftware (als Schlüssel) und die aktuell installierte Version enthält. ## Die IDs der Systemsoftware und der Version bestimmen -Zunächst musst du die IDs der Systemsoftware und der Version bestimmen, zu der du wechseln möchtest. Dies kannst du tun, indem du den `GET /v2/systemsoftwares`-Endpunkt aufrufst und das Ergebnis nach der gewünschten `.name`-Eigenschaft filterst. +Zunächst musst du die IDs der Systemsoftware und der Version bestimmen, zu der du wechseln möchtest. Dies kannst du tun, indem du den -Endpunkt aufrufst und das Ergebnis nach der gewünschten `.name`-Eigenschaft filterst. -Mithilfe dieser ID kannst du dann den `GET /v2/systemsoftwares/{systemSoftwareId}/versions`-Endpunkt aufrufen, um eine Liste aller verfügbaren Versionen für diese Systemsoftware zu erhalten. Um nur bestimmte Versionen auszuwählen, kannst du den `versionRange`-Query-Parameter verwenden. Dieser Parameter akzeptiert jede gültige [semantische Versionsbedingung](https://devhints.io/semver), wie z.B. `>= 14.0.0` oder `^14.0.0`. +Mithilfe dieser ID kannst du dann den -Endpunkt aufrufen, um eine Liste aller verfügbaren Versionen für diese Systemsoftware zu erhalten. Um nur bestimmte Versionen auszuwählen, kannst du den `versionRange`-Query-Parameter verwenden. Dieser Parameter akzeptiert jede gültige [semantische Versionsbedingung](https://devhints.io/semver), wie z.B. `>= 14.0.0` oder `^14.0.0`. ## Verändern der Systemsoftware-Version -Um die Systemsoftware-Version zu verändern, verwende den `PATCH /v2/appinstallations/{appinstallationId}`-Endpunkt. Du musst nur die `.systemSoftware`-Eigenschaft im Request-Body angeben, die die ID der Systemsoftware und die Version enthält, zu der du wechseln möchtest: +Um die Systemsoftware-Version zu verändern, verwende den -Endpunkt. Du musst nur die `.systemSoftware`-Eigenschaft im Request-Body angeben, die die ID der Systemsoftware und die Version enthält, zu der du wechseln möchtest: ``` PATCH /v2/appinstallations/{appInstallationId} HTTP/1.1 diff --git a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-nodejs.mdx b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-nodejs.mdx index c2346bda..8ce2aeb8 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-nodejs.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-nodejs.mdx @@ -8,6 +8,7 @@ tags: --- import OperationHint from "@site/src/components/OperationHint"; +import OperationLink from "@site/src/components/OperationLink"; ### Voraussetzungen @@ -20,18 +21,18 @@ Um eine Node.js- oder Python-Anwendung zu installieren, benötigst Du Folgendes: Bevor Du eine Node.js- oder Python-Anwendung installierst, musst Du die App-ID und die Versions-ID der generischen benutzerdefinierten Node.js- bzw. Python-Anwendung bestimmen. -Hierzu rufe die `/v2/apps`-Endpunkt auf und suche die "Node.js"- oder "Python"-Anwendung. Diese sollten die folgenden (stabilen) IDs haben: +Hierzu rufe die -Endpunkt auf und suche die "Node.js"- oder "Python"-Anwendung. Diese sollten die folgenden (stabilen) IDs haben: - Node.js: `3e7f920b-a711-4d2f-9871-661e1b41a2f0` - Python: `be57d166-dae9-4480-bae2-da3f3c6f0a2e` -Wähle die entsprechende Anwendungs-ID, je nachdem, ob du eine Node.js- oder Python-Anwendung installieren möchtest. Du kannst dann diese ID verwenden, um die empfohlene Version für diese App abzurufen, indem Du den `/v2/apps/{appID}/versions`-Endpunkt aufrufst. Du kannst die zurückgegebenen Versionen nach der `recommended`-Eigenschaft filtern. +Wähle die entsprechende Anwendungs-ID, je nachdem, ob du eine Node.js- oder Python-Anwendung installieren möchtest. Du kannst dann diese ID verwenden, um die empfohlene Version für diese App abzurufen, indem Du den -Endpunkt aufrufst. Du kannst die zurückgegebenen Versionen nach der `recommended`-Eigenschaft filtern. Beachte, dass die tatsächliche Version weitgehend unerheblich ist, da sie nur auf die Starter-Vorlage verweist, die zur Erstellung der Anwendung verwendet wird. Die tatsächliche Version der Anwendung wird durch Deinen eigenen Code bestimmt. ### Installieren der Anwendung -Um Deine Anwendung bereitzustellen, rufe den `POST /v2/projects/{projectID}/appinstallations`-Endpunkt auf. Die relevanten Felder sind die folgenden: +Um Deine Anwendung bereitzustellen, rufe den -Endpunkt auf. Die relevanten Felder sind die folgenden: - `appVersionId` sollte die App-Version-ID sein, die Du im vorherigen Schritt abgerufen hast. - `userInputs` sollte ein Array von Objekten sein, die jeweils eine `name`- und eine `value`-Eigenschaft enthalten. Im Fall von Node.js ist der einzige zulässige Wert für `name` der Wert `entrypoint`. Der dazugehörige `value` ist der Befehl, der ausgeführt wird, um Deine Anwendung zu starten. @@ -54,8 +55,8 @@ Content-Type: application/json } ``` - + Die Antwort enthält die Installations-ID, die Du anschließend verwenden kannst, um auf Deine Anwendung zuzugreifen. -Um den Installationsstatus zu überwachen, rufe den `/v2/appinstallations/{installationID}`-Endpunkt auf. Beachte das Feld `installationPath`, das das Verzeichnis in Deinem Projekt-Dateisystem enthält, in das Du Deine Anwendung bereitstellen solltest. +Um den Installationsstatus zu überwachen, rufe den -Endpunkt auf. Beachte das Feld `installationPath`, das das Verzeichnis in Deinem Projekt-Dateisystem enthält, in das Du Deine Anwendung bereitstellen solltest. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-project.mdx b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-project.mdx index d73c95e3..5e6493f9 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-project.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-project.mdx @@ -21,9 +21,9 @@ Es gibt verschiedene Möglichkeiten, ein neues Projekt zu erstellen: ### ...auf einem Server -Voraussetzung dafür, ein Projekt auf einem bestehenden Server zu erstellen, ist die ID dieses Servers. Du kannst alle Server finden, auf die du Zugriff hast, indem du den `GET /v2/servers`-API-Endpunkt verwendest. +Voraussetzung dafür, ein Projekt auf einem bestehenden Server zu erstellen, ist die ID dieses Servers. Du kannst alle Server finden, auf die du Zugriff hast, indem du den -Endpunkt verwendest. -Um ein neues Projekt zu erstellen, sende eine `POST`-Anfrage an den `/v2/servers/{serverID}/projects`-Endpunkt. Der Anfragetext muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: +Um ein neues Projekt zu erstellen, sende eine Anfrage an den -Endpunkt. Der Anfragetext muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: - `description` (String, Pflichtfeld) sollte eine menschenlesbare Beschreibung des Projekts enthalten. @@ -31,7 +31,7 @@ Die Antwort im Erfolgsfall enthält ein JSON-Objekt mit den folgenden Eigenschaf - `id` ist die ID des neu erstellten Projekts. - + ### ...als Standalone-Projekt @@ -43,8 +43,8 @@ Das Erstellen von Standalone-Projekten wird derzeit nicht unterstützt. ## Überprüfen der Projekt-Verfügbarkeit -Ein neu erstelltes Projekt ist nicht sofort verfügbar (sollte es jedoch innerhalb weniger Sekunden sein). Um zu überprüfen, ob ein Projekt bereit ist, sende eine `GET`-Anfrage an den `/v2/projects/{projectID}`-Endpunkt. Unter anderem enthält die Antwort eine `isReady`-Eigenschaft. Diese Eigenschaft ist `true`, wenn das Projekt bereitgestellt und verfügbar ist, und andernfalls `false`. +Ein neu erstelltes Projekt ist nicht sofort verfügbar (sollte es jedoch innerhalb weniger Sekunden sein). Um zu überprüfen, ob ein Projekt bereit ist, sende eine Anfrage an den -Endpunkt. Unter anderem enthält die Antwort eine `isReady`-Eigenschaft. Diese Eigenschaft ist `true`, wenn das Projekt bereitgestellt und verfügbar ist, und andernfalls `false`. - + [^1]: https://www.mittwald.de/space-server diff --git a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-redis.mdx b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-redis.mdx index 478edc2d..d35747b0 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-redis.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/create-redis.mdx @@ -20,28 +20,28 @@ Um eine Redis-Datenbank zu erstellen, benötigst Du Zugriff auf ein Projekt. Wie ## Liste verfügbarer Redis-Versionen -Sende eine `GET`-Anfrage an den Endpunkt `/v2/redis-versions`, um eine Liste der verfügbaren Redis-Versionen zu erhalten (Dokumentation für den `database-list-redis-versions`-Endpunkt). +Sende eine `GET`-Anfrage an den -Endpunkt, um eine Liste der verfügbaren Redis-Versionen zu erhalten. ## Erstellen einer Redis-Datenbank -Um eine Redis-Datenbank zu erstellen, sende eine `POST`-Anfrage an den Endpunkt `/v2/projects/{projectID}/redis-databases`. Der Anfrage-Body muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: +Um eine Redis-Datenbank zu erstellen, sende eine Anfrage an den -Endpunkt. Der Anfrage-Body muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: - `description` sollte eine für Menschen lesbare Beschreibung der Datenbank enthalten. Dies ist ein Pflichtwert. -- `version` sollte die Version der Datenbank enthalten. Dies ist ein Pflichtwert und muss auf eine vorhandene Version verweisen, die vom Endpunkt `/v2/redis-versions` zurückgegeben wird. +- `version` sollte die Version der Datenbank enthalten. Dies ist ein Pflichtwert und muss auf eine vorhandene Version verweisen, die vom Endpunkt zurückgegeben wird. Die Antwort enthält die folgenden Eigenschaften: - `id` enthält die ID der erstellten Datenbank. - + ## Zugriff auf die Datenbank -Nachdem Du eine Datenbank erstellt hast, kannst Du eine `GET`-Anfrage an den Pfad `/v2/redis-databases/{id}` senden. +Nachdem Du eine Datenbank erstellt hast, kannst Du eine Anfrage an den -Endpunkt senden. Die Antwort enthält unter anderem die folgenden Werte: - `hostname` und `port` enthalten den Hostnamen und den Port der Datenbank. Du kannst diese Werte verwenden, um dich von deiner Hosting-Umgebung aus mit der Datenbank zu verbinden. - `configuration` ermöglicht es Dir, die spezifischen Konfigurationswerte einzusehen, die auf Deine Datenbank angewendet wurden. - + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/manage-mailbox.mdx b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/manage-mailbox.mdx index 1afdf5f2..f70ff2bb 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/manage-mailbox.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/api/howtos/manage-mailbox.mdx @@ -7,6 +7,7 @@ description: | --- import OperationHint from "@site/src/components/OperationHint"; +import OperationLink from "@site/src/components/OperationLink"; import SchemaFromSpec from "@site/src/components/openapi/SchemaFromSpec"; ## Arten von E-Mail-Konten @@ -22,7 +23,7 @@ Um E-Mail-Konten zu verwalten, benötigst du ein bestehendes Projekt. Um ein neu ## Ein neues E-Mail-Konto erstellen -Um ein neues E-Mail-Konto zu erstellen, sende eine `POST`-Anfrage an den `/v2/projects/{projectID}/mailaddresses`-Endpunkt. Die Anfrage muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: +Um ein neues E-Mail-Konto zu erstellen, sende eine Anfrage an den -Endpunkt. Die Anfrage muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: + ## Eine neue Weiterleitungsadresse erstellen -Eine Weiterleitungsadresse ist eine E-Mail-Adresse, die alle eingehenden E-Mails an eine oder mehrere andere E-Mail-Adressen weiterleitet. Um eine neue Weiterleitungsadresse zu erstellen, sende eine `POST`-Anfrage an den `/v2/projects/{projectID}/mailaddresses`-Endpunkt. Die Anfrage muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: +Eine Weiterleitungsadresse ist eine E-Mail-Adresse, die alle eingehenden E-Mails an eine oder mehrere andere E-Mail-Adressen weiterleitet. Um eine neue Weiterleitungsadresse zu erstellen, sende eine Anfrage an den -Endpunkt. Die Anfrage muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: -Endpunkt. Die Anfrage muss ein JSON-Objekt mit den folgenden Eigenschaften enthalten: - `description` (String, Pflichtfeld): Eine Beschreibung des Postausgangs. Diese Beschreibung wird in der Web-Oberfläche angezeigt. - `password` (String, Pflichtfeld): Das Passwort für den Postausgang. Dieses Passwort wird verwendet, um sich gegenüber dem SMTP-Server zu authentifizieren. @@ -65,4 +66,6 @@ Merke dir das Passwort, das du für das E-Mail-Konto festgelegt hast. Du hast sp ## E-Mail-Konten löschen -Um eine E-Mail-Adresse oder Postausgang zu löschen, sende eine `DELETE`-Anfrage an den `/v2/mailaddresses/{id}` oder `/v2/deliveryboxes/{id}`-Endpunkt (je nachdem, welches Konto du löschen möchtest). Der `id`-Parameter muss die ID der E-Mail-Adresse oder des Postausgangs enthalten, den du löschen möchtest. Es ist kein Request-Body erforderlich. +Um eine E-Mail-Adresse oder Postausgang zu löschen, sende eine Anfrage an den - oder -Endpunkt (je nachdem, welches Konto du löschen möchtest). Der `id`-Parameter muss die ID der E-Mail-Adresse oder des Postausgangs enthalten, den du löschen möchtest. Es ist kein Request-Body erforderlich. + + \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/api/intro.md b/i18n/de/docusaurus-plugin-content-docs/current/api/intro.mdx similarity index 93% rename from i18n/de/docusaurus-plugin-content-docs/current/api/intro.md rename to i18n/de/docusaurus-plugin-content-docs/current/api/intro.mdx index e0037872..1ca06670 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/api/intro.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/api/intro.mdx @@ -5,6 +5,8 @@ description: | Diese Seite bietet eine Einführung in die mStudio v2 API und ihre Konzepte. --- +import OperationLink from "@site/src/components/OperationLink"; + ## Basis-URLs Die mStudio v2 API verwendet `https://api.mittwald.de/v2/` als Basis-URL für alle API-Endpunkte. @@ -23,10 +25,10 @@ Die vollständige API-Spezifikation im [OpenAPI 3.0-Format](https://spec.openapi Um dich an der API zu authentifizieren, benötigst du ein **API-Token**. Du kannst es entweder über die mittwald mStudio Web-UI oder über die API selbst beziehen (wenn du bereits über ein anderes API-Token verfügst). 1. **In der Web-UI** gehe zu deinem Benutzerprofil und wähle den Menüpunkt [API-Tokens](https://studio.mittwald.de/app/profile/api-tokens) aus. -2. Alternativ, **über die API**, verwende den `/v2/signup/token/api`-Endpunkt. Dieser setzt voraus, dass du ein bereits bestehendes API-Token hast: +2. Alternativ, **über die API**, verwende den -Endpunkt. Dieser setzt voraus, dass du ein bereits bestehendes API-Token hast: ```http - POST /v2/signup/token/api HTTP/1.1 + POST /v2/users/self/api-tokens HTTP/1.1 Host: api.mittwald.de Content-Type: application/json Authorization: Bearer diff --git a/i18n/de/docusaurus-theme-classic/footer.json b/i18n/de/docusaurus-theme-classic/footer.json index bd1d124d..a265701b 100644 --- a/i18n/de/docusaurus-theme-classic/footer.json +++ b/i18n/de/docusaurus-theme-classic/footer.json @@ -49,7 +49,7 @@ }, "link.item.label.Reference": { "message": "Referenz", - "description": "The label of footer link with label=Reference linking to /docs/v2/category/reference" + "description": "The label of footer link with label=Reference linking to /docs/v2/reference" }, "link.item.label.Platform": { "message": "Plattform", diff --git a/i18n/en/code.json b/i18n/en/code.json index 664bbebe..7c7940f7 100644 --- a/i18n/en/code.json +++ b/i18n/en/code.json @@ -328,6 +328,9 @@ "components.OperationHint.text": { "message": "For details please refer to the endpoint documentation for the following endpoint" }, + "components.OperationHint.text.plural": { + "message": "For details please refer to the endpoint documentations for the following endpoints" + }, "compat.title": { "message": "Compatibility notice" }, diff --git a/src/components/OperationHint/index.tsx b/src/components/OperationHint/index.tsx index ae9aaf81..dbb8b0bc 100644 --- a/src/components/OperationHint/index.tsx +++ b/src/components/OperationHint/index.tsx @@ -1,25 +1,30 @@ import React from "react"; - -import Admonition from "@theme/Admonition"; import Translate from "@docusaurus/Translate"; -import OperationLink from "../OperationLink"; +import OperationDocCardById from "@site/src/components/openapi/OperationDocCardById"; +import InlineAlert from "@mittwald/flow-react-components/InlineAlert"; +import Content from "@mittwald/flow-react-components/Content"; +import Heading from "@mittwald/flow-react-components/Heading"; +import styles from "./styles.module.css"; export interface OperationHintProps { - tag: string; - operation: string; + operation: string | string[]; } -export default function OperationHint({ tag, operation }: OperationHintProps) { +export default function OperationHint({ operation }: OperationHintProps) { + operation = Array.isArray(operation) ? operation : [operation]; + + const heading = operation.length > 1 ? + : + ; + return ( - - - For details please refer to the endpoint documentation for the following - endpoint - - :{" "} - - {operation} - - + + {heading}: + +
+ {operation.map((o, idx) => )} +
+ + ); } diff --git a/src/components/OperationHint/styles.module.css b/src/components/OperationHint/styles.module.css new file mode 100644 index 00000000..494289af --- /dev/null +++ b/src/components/OperationHint/styles.module.css @@ -0,0 +1,8 @@ +.operations { + flex: 1; + width: 100%; +} + +.operations .card { + width: 100%; +} \ No newline at end of file diff --git a/src/components/OperationLink/index.tsx b/src/components/OperationLink/index.tsx index bb8c0e1d..93363022 100644 --- a/src/components/OperationLink/index.tsx +++ b/src/components/OperationLink/index.tsx @@ -1,17 +1,34 @@ import React, { PropsWithChildren } from "react"; import Link from "@docusaurus/Link"; +import { getOperationById, useSpec } from "@site/src/openapi/specs"; +import HTTPMethod from "@site/src/components/openapi/HTTPMethod"; +import OperationPath from "@site/src/components/openapi/OperationPath"; +import styles from "./styles.module.css"; export interface OperationLinkProps { - tag: string; operation: string; } export default function OperationLink({ - tag, - operation, - children, -}: PropsWithChildren) { - children = children || {operation}; + operation, + children + }: PropsWithChildren) { + const spec = useSpec("v2"); + const operationSpec = getOperationById(spec, operation); + + if (!operationSpec) { + return <>unknown operation {operation}; + } + + const tag = operationSpec.operation.tags[0]; + const summary = operationSpec.operation.summary.replace(/\.$/, ""); + + children = children || + + + + + ; const url = `/docs/v2/reference/${tag.toLowerCase()}/${operation}`; return {children}; diff --git a/src/components/OperationLink/styles.module.css b/src/components/OperationLink/styles.module.css new file mode 100644 index 00000000..267ef0b2 --- /dev/null +++ b/src/components/OperationLink/styles.module.css @@ -0,0 +1,5 @@ +.operationLink { + background-color: var(--ifm-code-background); + border-radius: var(--ifm-code-border-radius); + display: inline-flex; +} \ No newline at end of file diff --git a/src/components/PlanCompatibility/index.tsx b/src/components/PlanCompatibility/index.tsx index 08b43691..87ddd3aa 100644 --- a/src/components/PlanCompatibility/index.tsx +++ b/src/components/PlanCompatibility/index.tsx @@ -1,8 +1,8 @@ import React, { ReactNode } from "react"; import styles from "./styles.module.css"; -import Translate from "@docusaurus/Translate"; -import clsx from "clsx"; +import Translate, { translate } from "@docusaurus/Translate"; import Link from "@docusaurus/Link"; +import Admonition from "@theme/Admonition"; type PlanDefinition = { name: string; @@ -12,7 +12,7 @@ type PlanDefinition = { const planNames: Record = { psl: { name: "proSpace lite", url: "https://www.mittwald.de/prospace" }, ps: { name: "proSpace", url: "https://www.mittwald.de/prospace" }, - ss: { name: "Space Server", url: "https://www.mittwald.de/space-server" }, + ss: { name: "Space Server", url: "https://www.mittwald.de/space-server" } }; export interface PlanCompatibilityProps { @@ -26,22 +26,19 @@ export default function PlanCompatibility({ plans }: PlanCompatibilityProps) { {planNames[plan].name} - ), + ) ) .map((n): ReactNode => {n}) .reduce((prev, curr) => [prev, ", ", curr]); return ( -
-
- ⚠︎ Compatibility notice -
-
+ +

This documentation applies only to the following plans : {names}. -

-
+

+ ); } diff --git a/src/components/openapi/HTTPMethod.module.css b/src/components/openapi/HTTPMethod.module.css index 6ba384ce..660a9e2d 100644 --- a/src/components/openapi/HTTPMethod.module.css +++ b/src/components/openapi/HTTPMethod.module.css @@ -8,6 +8,13 @@ display: inline-block; min-width: 80px; text-align: center; + font-family: var(--ifm-font-family-base); +} + +p .method, li .method { + font-size: 0.8rem; + padding: 0 8px; + min-width: 0; } .methodDeprecated { diff --git a/src/components/openapi/OperationDocCard.module.css b/src/components/openapi/OperationDocCard.module.css index 2b8f2d2c..156952a5 100644 --- a/src/components/openapi/OperationDocCard.module.css +++ b/src/components/openapi/OperationDocCard.module.css @@ -6,6 +6,10 @@ transition-property: border, box-shadow; } +.card.compact { + padding: calc(var(--ifm-global-spacing) / 2) !important; +} + .header { display: flex; align-items: flex-start; diff --git a/src/components/openapi/OperationDocCard.tsx b/src/components/openapi/OperationDocCard.tsx index 767236bc..ae1e6b72 100644 --- a/src/components/openapi/OperationDocCard.tsx +++ b/src/components/openapi/OperationDocCard.tsx @@ -12,10 +12,11 @@ import buildDocumentId from "@site/src/openapi/buildDocumentId"; interface Props { apiVersion: APIVersion; operation: OperationWithMeta; + variant?: "compact"; } -function OperationDocCard(p: Props) { - const { apiVersion } = p; +export default function OperationDocCard(p: Props) { + const { apiVersion, variant } = p; const { operation, method, path } = p.operation; const deprecated = isDeprecated(operation); const docId = buildDocumentId(operation); @@ -24,9 +25,10 @@ function OperationDocCard(p: Props) {
@@ -48,5 +50,3 @@ function OperationDocCard(p: Props) {
); } - -export default OperationDocCard; diff --git a/src/components/openapi/OperationDocCardById.tsx b/src/components/openapi/OperationDocCardById.tsx new file mode 100644 index 00000000..bd7706ce --- /dev/null +++ b/src/components/openapi/OperationDocCardById.tsx @@ -0,0 +1,21 @@ +import { APIVersion, getOperationById, useSpec } from "@site/src/openapi/specs"; +import OperationDocCard from "@site/src/components/openapi/OperationDocCard"; + +interface Props { + operationId: string; + apiVersion?: APIVersion; + variant?: "compact"; +} + +export default function OperationDocCardById({ operationId, apiVersion = "v2", variant }: Props) { + const spec = useSpec(apiVersion); + const operation = getOperationById(spec, operationId); + + if (operation) { + return ( + + ); + } + + return <>unknown operation {operationId}; +} \ No newline at end of file diff --git a/src/components/openapi/OperationMetadata.tsx b/src/components/openapi/OperationMetadata.tsx index 554bdf51..58899a1e 100644 --- a/src/components/openapi/OperationMetadata.tsx +++ b/src/components/openapi/OperationMetadata.tsx @@ -94,7 +94,9 @@ export function OperationMetadata({
- {spec.description && withDescription ? {spec.description} : null} + {spec.description && withDescription ? ( + {spec.description} + ) : null} ); } diff --git a/src/components/openapi/OperationUsage.tsx b/src/components/openapi/OperationUsage.tsx index 09d2d723..d9473097 100644 --- a/src/components/openapi/OperationUsage.tsx +++ b/src/components/openapi/OperationUsage.tsx @@ -32,33 +32,33 @@ export function OperationUsage(props: OperationUsageProps) { children = [children]; } - if (withPHP && !children.some(i => i.key === "php")) { + if (withPHP && !children.some((i) => i.key === "php")) { children.unshift( {generatePHPCodeExample(method, url, spec, baseURL)} - + , ); } - if (withJavascript && !children.some(i => i.key === "javascript")) { + if (withJavascript && !children.some((i) => i.key === "javascript")) { children.unshift( {generateJavascriptCodeExample(method, url, spec, baseURL)} - + , ); } - if (!children.some(i => i.key === "curl")) { + if (!children.some((i) => i.key === "curl")) { children.unshift( {generateCurlCodeExample(method, url, spec, baseURL)} - + , ); } diff --git a/src/css/custom.css b/src/css/custom.css index 51651ed2..b4fd0aa2 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -182,7 +182,7 @@ a.menu__link { } aside { - border: none !important; + /*border: none !important;*/ clip-path: none !important; } @@ -548,3 +548,7 @@ section.row { min-width: 48px; text-align: center; } + +.flow--inline-alert { + margin-bottom: var(--ifm-leading); +} diff --git a/src/openapi/specs.ts b/src/openapi/specs.ts index e451c988..87a139f9 100644 --- a/src/openapi/specs.ts +++ b/src/openapi/specs.ts @@ -19,6 +19,23 @@ export function useSpec(version: APIVersion) { return specs[version]; } +export function getOperationById( + spec: OpenAPIV3.Document, + operationId: string, +): OperationWithMeta | undefined { + for (const path of Object.keys(spec.paths)) { + for (const method of Object.keys(spec.paths[path])) { + const operation = spec.paths[path][method]; + + if (operation.operationId === operationId) { + return { path, method, operation }; + } + } + } + + return undefined; +} + export function getOperationByTag( spec: OpenAPIV3.Document, tag: string, diff --git a/src/theme/Admonition/index.tsx b/src/theme/Admonition/index.tsx new file mode 100644 index 00000000..724ff0ce --- /dev/null +++ b/src/theme/Admonition/index.tsx @@ -0,0 +1,36 @@ +import React from "react"; +import type AdmonitionType from "@theme/Admonition"; +import type { WrapperProps } from "@docusaurus/types"; +import InlineAlert from "@mittwald/flow-react-components/InlineAlert"; +import Heading from "@mittwald/flow-react-components/Heading"; +import Content from "@mittwald/flow-react-components/Content"; +import { translate } from "@docusaurus/Translate"; + +type Props = WrapperProps; + +export default function AdmonitionWrapper(props: Props): JSX.Element { + const status = { + note: "info", + caution: "warning", + warning: "warning", + }; + + return ( + + + {props.title ?? + translate({ + id: `theme.admonition.${props.type}`, + message: props.type, + })} + + {props.children} + + ); + + // return ( + // <> + // + // + // ); +}