feat(docs): update descriptions of all endpoint

stfsy · stfsy · commit bac372bfeb97 · 2022-06-13T20:56:47.000+02:00
diff --git a/docs/api-reference/api-keys/create-an-api-key.md b/docs/api-reference/api-keys/create-an-api-key.md
@@ -20,7 +20,7 @@ api:
 <span class="font-medium">POST</span> /api_keys
 </p>
 
-Creates a new API key and returns the actual key. 
+**Creates** a new API key and returns the actual key. 
 
 <Badge type="warning" text="Note" vertical="middle"/> For security reasons, the 
 API key will only be returned once after its creation.
diff --git a/docs/api-reference/api-keys/delete-an-api-key-by-id.md b/docs/api-reference/api-keys/delete-an-api-key-by-id.md
@@ -20,8 +20,14 @@ api:
 <span class="font-medium">DELETE</span> /api_keys/{api_key_id}
 </p>
 
-Updates an api key by id. Requires the id of the target api to be passed via path parameter. 
-Returns `404` if no api key was found with the given `api_key_id`. 
+**Deletes** an api key by id. **Requires** the target 
+`api_key_id` as a path parameter.
+
+A valid `api_key_id` is one that was returned by the 
+[api key creation endpoint](/api-reference/api-keys/create-an-api-key.html).
+If no api key can be found with the given `api_key_id`, the endpoint returns status `404`.
+
+Returns `404` if no api key was found with the given `api_key_id`.
 
 <Badge type="danger" text="Warning" vertical="middle"/> As a result of calling this endpoint
 <strong>the target api key will be deleted.</strong> 
diff --git a/docs/api-reference/api-keys/get-all-api-keys.md b/docs/api-reference/api-keys/get-all-api-keys.md
@@ -20,11 +20,11 @@ api:
 <span class="font-medium">GET</span> /api_keys
 </p>
 
-Returns all API keys created
+**Returns** all API keys created
 by the [create api key endpoint](/api-reference/api-keys/create-an-api-key.html).
 
-All returned keys are redacted. Thus, the endpoint never returns the actual key value. The endpoint
-will, however, return meta data of each key like the time it was created and its current status.
+All returned keys are redacted. Thus, the endpoint never returns the actual key value. The endpoint, 
+however, returns meta data of each key like the time it was created and its current status.
 
 The result may be inconistent as in not update-to-date as results may be cached
 for a short period of time.
diff --git a/docs/api-reference/api-keys/get-an-api-key-by-id.md b/docs/api-reference/api-keys/get-an-api-key-by-id.md
@@ -20,8 +20,12 @@ api:
 <span class="font-medium">GET</span> /api_keys/{api_key_id}
 </p>
 
-Returns an api key by id. The api key will be identified by the required `api_key_id` path parameter.
-In case a key cannot be found, the endpoint will return `404`.
+**Returns** an api key by id. **Requires** the target 
+`api_key_id` as a path parameter.
+
+A valid `api_key_id` is one that was returned by the 
+[api key creation endpoint](/api-reference/api-keys/create-an-api-key.html).
+If no api key can be found with the given `api_key_id`, the endpoint returns status `404`.
 
 All returned keys are redacted. Thus, the endpoint never returns the actual key value. The endpoint
 will, however, return meta data of a key like the time it was created and its current status.
diff --git a/docs/api-reference/api-keys/update-an-api-key-by-id.md b/docs/api-reference/api-keys/update-an-api-key-by-id.md
@@ -20,9 +20,16 @@ api:
 <span class="font-medium">PUT</span> /api_keys/{api_key_id}
 </p>
 
-Updates an api key by id. Requires the id of the target api to be passed via path parameter. 
+**Updates** an api key by id. **Requires** the target 
+`api_key_id` as a path parameter.
 
-Returns `404` if no api key was found with the given `api_key_id`. 
+A valid `api_key_id` is one that was returned by the 
+[api key creation endpoint](/api-reference/api-keys/create-an-api-key.html).
+If no api key can be found with the given `api_key_id`, the endpoint returns status `404`.
+
+Returns `404` if no api key was found with the given `api_key_id`.
+
+Only mutable properties like `name` can be updated.
 
 ::: tip Authentication
 **The target organization for this request will be determined by the supplied access token.** 
diff --git a/docs/api-reference/organizations/create-an-api-client.md b/docs/api-reference/organizations/create-an-api-client.md
@@ -20,10 +20,12 @@ api:
 <span class="font-medium">POST</span> /api_clients
 </p>
 
-Creates a new api client. **An api client groups resources like queues, listeners and messages**.
+**Creates a new api client**. 
+
+**An api client groups resources like queues, listeners and messages**.
 Users who need direct acces to the resources can be assigned to an organizations, too. 
 
-<Badge type="get" text="Info" vertical="middle"/> In this context an api client and an organization can be used synonymously. 
+<Badge type="get" text="Info" vertical="middle"/> In this context an api client and an organization can be used synonymously.
 
 ::: tip Authentication
 **The target organization for this request will be determined by the supplied access token.** 
diff --git a/docs/api-reference/queue-listeners/add-a-listener-to-a-queue.md b/docs/api-reference/queue-listeners/add-a-listener-to-a-queue.md
@@ -20,8 +20,12 @@ api:
 <span class="font-medium">POST</span> /queues/{queue_id}/listeners
 </p>
 
-Creates a new listener for a queue associated with the current organization. The `queue_id` path parameter
-must point to an existing queue created by [add a queue endpoint](/api-reference/queues/create-a-queue.html).
+**Creates** a new listener for a queue. **Requires** the 
+target `queue_id` as a path parameter.
+
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). 
+If no queue with the given `queue_id` can be found, the endpoint returns status `404`.
 
 This endpoint returns the listeners's unique identifier, the `listener_id`. This identifier
 must be passed to the following listener endpoints to update or delete the listener. 
diff --git a/docs/api-reference/queue-listeners/delete-a-listener-by-id.md b/docs/api-reference/queue-listeners/delete-a-listener-by-id.md
@@ -20,9 +20,13 @@ api:
 <span class="font-medium">DELETE</span> /queues/{queue_id}/listeners/{listener_id}
 </p>
 
-Deletes a listener by id. To identify the target listener a `queue_id` and a `listener_id` must be passed as a path parameter. 
+**Deletes** a listener by id. Requires a valid `queue_id` and `listener_id` as path parameters.
 If no queue or listener with the given ids can be found, the endpoint returns status `404`.
 
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). The `listener_id` is the one 
+returned by the [create listener endpoint](/api-reference/queue-listeners/add-a-listener-to-a-queue.html).
+
 <Badge type="danger" text="Warning" vertical="middle"/> As a result of calling this endpoint
 <strong>the target listener will be deleted and sent to the shadow realm</strong>. This process cannot be reverted.
 
diff --git a/docs/api-reference/queue-listeners/get-a-listener-by-id.md b/docs/api-reference/queue-listeners/get-a-listener-by-id.md
@@ -20,11 +20,12 @@ api:
 <span class="font-medium">GET</span> /queues/{queue_id}/listeners/{listener_id}
 </p>
 
-Returns a listener by id. Requires a valid `queue_id` and `listener_id` as prerequisite.
+**Returns** a queue listener by id. Requires a valid `queue_id` and `listener_id` as path parameters.
 If no queue or listener with the given ids can be found, the endpoint returns status `404`.
 
-Use [this endpoint](/api-reference/queues/create-a-queue.html) to create a queue, and 
-[this endpoint](/api-reference/queue-listeners/add-a-listener-to-a-queue.html) to create a listener.
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). The `listener_id` is the one 
+returned by the [create listener endpoint](/api-reference/queue-listeners/add-a-listener-to-a-queue.html).
 
 The result may be inconistent as in not update-to-date as results may be cached
 for a short period of time.
diff --git a/docs/api-reference/queue-listeners/get-all-listeners.md b/docs/api-reference/queue-listeners/get-all-listeners.md
@@ -20,8 +20,9 @@ api:
 <span class="font-medium">GET</span> /listeners
 </p>
 
-Returns the list of all listeners associated with the current organization. Use this method
-to get an overview of all listeners created via the
+**Returns** the list of all listeners. 
+
+Use this method to get an overview of all listeners created via the
 [add a listener to a queue endpoint](/api-reference/queue-listeners/add-a-listener-to-a-queue.html).
 
 As this endpoint is not bound to a specific queue, it will return **all listeners**
diff --git a/docs/api-reference/queue-listeners/get-all-queue-listeners-by-id.md b/docs/api-reference/queue-listeners/get-all-queue-listeners-by-id.md
@@ -20,11 +20,14 @@ api:
 <span class="font-medium">GET</span> /queues/{queue_id}/listeners
 </p>
 
-Returns all listeners of a queue with  `queue_id`. **The target queue must exist 
-and must be associated with the current organization**. If the queue was not created by calling the 
-[queue creation endpoint](/api-reference/queues/create-a-queue.html), or the 
-`queue_id` is wrong, the endpoint returns status `404`. Use this method 
-if you are only interested in the listeners of a specific queue.
+**Returns** all listeners of the queue with  `queue_id`. **Requires** the target 
+`queue_id` as a path parameter.
+
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). 
+If no queue with the given `queue_id` can be found, the endpoint returns status `404`.
+
+Use this method if you are only interested in the listeners of a specific queue.
 
 The result may be inconistent as in not update-to-date as results may be cached
 for a short period of time.
diff --git a/docs/api-reference/queue-listeners/update-a-listener-by-id.md b/docs/api-reference/queue-listeners/update-a-listener-by-id.md
@@ -20,10 +20,14 @@ api:
 <span class="font-medium">PUT</span> /queues/{queue_id}/listeners/{listener_id}
 </p>
 
-Updates a listener by id. To identify the target listener, a `queue_id` and a `listener_id` must be passed as a path parameter. 
+**Updates** a queue listener by id. Requires a valid `queue_id` and `listener_id` as path parameters.
 If no queue or listener with the given ids can be found, the endpoint returns status `404`.
 
-Only **mutable** properties like `name`, `notify_url`, `liveness_url` can be updated. 
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). The `listener_id` is the one 
+returned by the [create listener endpoint](/api-reference/queue-listeners/add-a-listener-to-a-queue.html).
+
+Only **mutable** properties like `name`, `notify_url`, `liveness_url` can be updated.
 
 ::: tip Authentication
 **The target organization for this request will be determined by the supplied access token.** 
diff --git a/docs/api-reference/queue-messages/add-a-message-to-a-queue.md b/docs/api-reference/queue-messages/add-a-message-to-a-queue.md
@@ -20,8 +20,12 @@ api:
 <span class="font-medium">POST</span> /queues/{queue_id}/messages
 </p>
 
-Creates a new message and adds the message to the target queue. The `queue_id` path parameter
-must point to an existing queue created by [add a queue endpoint](/api-reference/queues/create-a-queue.html).
+**Creates** a new message and adds the message to the target queue. **Requires** the target 
+`queue_id` as a path parameter.
+
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). 
+If no queue with the given `queue_id` can be found, the endpoint returns status `404`.
 
 This endpoint returns the messages's unique identifier, the `message_id`. This identifier
 must be passed to the following endpoint to delete the message:
diff --git a/docs/api-reference/queue-messages/delete-a-message-by-id.md b/docs/api-reference/queue-messages/delete-a-message-by-id.md
@@ -20,8 +20,13 @@ api:
 <span class="font-medium">DELETE</span> /queues/{queue_id}/messages/{message_id}
 </p>
 
-Deletes a message by id. To identify the target message a `queue_id` and a `message_id` must be passed as a path parameter. 
-If no queue or message with the given ids can be found, the endpoint returns status `404`.
+**Deletes** a message by id. **Requires** the target 
+`queue_id` and `message_id` as a path parameter.
+
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). The `message_id` is the one
+returned by the [create message endpoint](/api-reference/queue-messages/add-a-message-to-a-queue.html).
+If no message can be found with the given `queue_id` or `listener_id`, the endpoint returns status `404`.
 
 <Badge type="danger" text="Warning" vertical="middle"/> As a result of calling this endpoint
 <strong>the target message will be deleted forever</strong>. This process cannot be reverted.
diff --git a/docs/api-reference/queue-messages/get-a-message-by-id.md b/docs/api-reference/queue-messages/get-a-message-by-id.md
@@ -20,11 +20,13 @@ api:
 <span class="font-medium">GET</span> /queues/{queue_id}/messages/{message_id}
 </p>
 
-Returns a message by id. Requires a valid `queue_id` and `message_id`.
-If no queue or message with the given ids can be found, the endpoint returns status `404`.
+**Returns** a message by id. **Requires** the target 
+`queue_id` and `message_id` as a path parameter.
 
-Beforehand, use [this endpoint](/api-reference/queues/create-a-queue.html) to create a queue, and 
-[this endpoint](/api-reference/queue-listeners/add-a-listener-to-a-queue.html) to add a message to it.
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). The `message_id` is the one
+returned by the [create message endpoint](/api-reference/queue-messages/add-a-message-to-a-queue.html).
+If no message can be found with the given `queue_id` or `listener_id`, the endpoint returns status `404`.
 
 The result may be inconistent as in not update-to-date as results may be cached
 for a short period of time.
diff --git a/docs/api-reference/queue-messages/get-all-messages.md b/docs/api-reference/queue-messages/get-all-messages.md
@@ -20,7 +20,7 @@ api:
 <span class="font-medium">GET</span> /messages
 </p>
 
-Returns the list of all messages associated with the current organization. Use this method
+**Returns** the list of all messages. Use this method 
 to get an overview of all messages created via the
 [add a message to a queue endpoint](/api-reference/queue-messages/add-a-message-to-a-queue.html).
 
diff --git a/docs/api-reference/queue-messages/get-messages-by-queue-id.md b/docs/api-reference/queue-messages/get-messages-by-queue-id.md
@@ -20,9 +20,12 @@ api:
 <span class="font-medium">GET</span> /queues/{queue_id}/messages
 </p>
 
-Returns all messages of a queue by id. Callees must pass a `queue_id` that was returned
-during [creation](/api-reference/queue-messages/add-a-message-to-a-queue.html) of the target
-queue.
+**Returns** all messages of a queue by id.  **Requires** the target 
+`queue_id` as a path parameter.
+
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). 
+If no queue with the given `queue_id` can be found, the endpoint returns status `404`.
 
 This endpoint can potentially return a large number of messages. This can lead to higher than average response times. 
 
diff --git a/docs/api-reference/queues/create-a-queue.md b/docs/api-reference/queues/create-a-queue.md
@@ -20,7 +20,7 @@ api:
 <span class="font-medium">POST</span> /queues
 </p>
 
-Creates a new queue associated with the current organization.
+**Creates** a new queue associated.
 
 This endpoint returns the queue's unique identifier, the `queue_id`. This identifier
 can be used for subsequent requests to 
diff --git a/docs/api-reference/queues/delete-a-queue-by-id.md b/docs/api-reference/queues/delete-a-queue-by-id.md
@@ -20,7 +20,10 @@ api:
 <span class="font-medium">DELETE</span> /queues/{queue_id}
 </p>
 
-Updates a queue by id. Obviously, **only existing queues can be deleted**. 
+**Deletes** a queue by id. **Requires** the target `queue_id` as a path parameter.
+
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). 
 If no queue with the given `queue_id` can be found, the endpoint returns status `404`.
 
 <Badge type="danger" text="Warning" vertical="middle"/> As a result of calling this endpoint
diff --git a/docs/api-reference/queues/get-a-queue-by-id.md b/docs/api-reference/queues/get-a-queue-by-id.md
@@ -20,10 +20,11 @@ api:
 <span class="font-medium">GET</span> /queues/{queue_id}
 </p>
 
-Returns a queue by id. **The target queue must be identified via the `queue_id` path parameter and
-must be associated with the current organization**. A valid `queue_id` is one that was returned by the 
-[queue creation endpoint](/api-reference/queues/create-a-queue.html). If no queue with the given `queue_id` 
-can be found, the endpoint returns status `404`.
+**Returns** a queue by id. **Requires** the target `queue_id` as a path parameter.
+
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). 
+If no queue with the given `queue_id` can be found, the endpoint returns status `404`.
 
 The result may be inconistent as in not update-to-date as results may be cached
 for a short period of time.
diff --git a/docs/api-reference/queues/get-all-queues.md b/docs/api-reference/queues/get-all-queues.md
@@ -20,7 +20,7 @@ api:
 <span class="font-medium">GET</span> /queues
 </p>
 
-Returns all queues associated with the current organization. That is queues that were created 
+**Returns** all queues. That is queues that were created 
 by calling the [create queue endpoint](/api-reference/queues/create-a-queue.html).
 
 The result may be inconistent as in not update-to-date as results may be cached
diff --git a/docs/api-reference/queues/update-a-queue-by-id.md b/docs/api-reference/queues/update-a-queue-by-id.md
@@ -20,12 +20,13 @@ api:
 <span class="font-medium">PUT</span> /queues/{queue_id}
 </p>
 
-Updates a queue by id. A `queue_id` must be passed as a path parameter. A valid `queue_id` 
-is created and returned during the queue creation process, which can be initiated by calling the 
-[queue creation endpoint](/api-reference/queues/create-a-queue.html)
+**Updates** a queue by id. **Requires** the target `queue_id` as a path parameter.
+
+A valid `queue_id` is one that was returned by the 
+[queue creation endpoint](/api-reference/queues/create-a-queue.html). 
 If no queue with the given `queue_id` can be found, the endpoint returns status `404`.
 
-Only mutable properties like `name` can be updated. 
+Only mutable properties like `name` can be updated.
 
 ::: tip Authentication
 **The target organization for this request will be determined by the supplied access token.** 
