add: run in postman (#90)

docs/tools/api.md

@@ -2,6 +2,8 @@
 title: Aiven API
 ---
 
+import RIP from "@site/static/includes/run-in-postman.md";
+
 Use the Aiven API to programmatically access and automate tasks in the Aiven platform.
 
 Common use cases for the Aiven API:
@@ -11,32 +13,19 @@ Common use cases for the Aiven API:
     complete complex tasks.
 -   Deploy and tear down development or demo platforms on a schedule.
 
-## API quickstart
-
--   View the [API documentation and OpenAPI
-    description](https://api.aiven.io/doc/).
--   Try the [Aiven API on
-    Postman](https://www.postman.com/aiven-apis/workspace/aiven/documentation/21112408-1f6306ef-982e-49f8-bdae-4d9fdadbd6cd).
-
-## Authentication
-
-Most endpoints require authentication.
-[Create an authentication token](docs/platform/howto/create_authentication_token.md)
-and send it in the header.
+## Get started
 
-You can use a structure like this:
+Use the [Postman workspace](https://www.postman.com/aiven-apis/workspace/aiven/overview)
+to try the Aiven API.
 
-```bash
-Authorization: aivenv1 TOKEN
-```
-
-Where `TOKEN` is your authentication token.
+1. [Create an authentication token](/docs/platform/howto/create_authentication_token).
+1. Fork the Postman **collection** and **environment**.
 
-## Handling JSON responses
+   <RIP/>
 
-The Aiven API returns information in JSON format. To get
-information in an easier-to-read format, you can use a tool like
-[`jq`](https://stedolan.github.io/jq/).
+1. Insert the token in the `authToken` in the Postman environment.
+1. See the [API documentation](https://api.aiven.io/doc/).
+1. Send your requests via Postman.
 
 ## API examples
 
@@ -163,7 +152,6 @@ You can use the `cloud_name` from this response as an input for other endpoints.
 
 ## Related pages
 
--   Read about
-    [authentication tokens](/docs/platform/concepts/authentication-tokens).
--   See more [API examples](https://aiven.io/blog/your-first-aiven-api-call).
--   Learn about the [Aiven CLI](/docs/tools/cli).
+- [Authentication tokens](/docs/platform/concepts/authentication-tokens)
+- [Aiven Provider for Terraform](https://registry.terraform.io/providers/aiven/aiven/latest/docs)
+- [API reference docs](https://api.aiven.io/doc/)

static/includes/run-in-postman.md

@@ -0,0 +1,3 @@
+<!-- vale off -->
+<a target="_blank" href="https://app.getpostman.com/run-collection/32630186-ad894eed-9287-4a30-8534-d2b4422a254a?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D32630186-ad894eed-9287-4a30-8534-d2b4422a254a%26entityType%3Dcollection%26workspaceId%3D85dcbab4-8e52-4836-839f-9157852fef73#?env%5BAiven%20environment%5D=W3sia2V5IjoiYXV0aFRva2VuIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoic2VjcmV0Iiwic2Vzc2lvblZhbHVlIjoiIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6ImJhc2VVcmwiLCJ2YWx1ZSI6Imh0dHBzOi8vYXBpLmFpdmVuLmlvL3YxIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiJodHRwczovL2FwaS5haXZlbi5pby92MSIsInNlc3Npb25JbmRleCI6MX0seyJrZXkiOiJhY2NvdW50X2lkIiwidmFsdWUiOiJpZCIsImVuYWJsZWQiOnRydWUsInNlc3Npb25WYWx1ZSI6ImlkIiwic2Vzc2lvbkluZGV4IjoyfSx7ImtleSI6InRlYW1faWQiLCJ2YWx1ZSI6ImlkIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoiaWQiLCJzZXNzaW9uSW5kZXgiOjN9LHsia2V5IjoicHJvamVjdCIsInZhbHVlIjoiaWQiLCJlbmFibGVkIjp0cnVlLCJzZXNzaW9uVmFsdWUiOiJpZCIsInNlc3Npb25JbmRleCI6NH0seyJrZXkiOiJiaWxsaW5nX2dyb3VwX2lkIiwidmFsdWUiOiJpZCIsImVuYWJsZWQiOnRydWUsInNlc3Npb25WYWx1ZSI6ImlkIiwic2Vzc2lvbkluZGV4Ijo1fSx7ImtleSI6InRlbmFudCIsInZhbHVlIjoidGVuYW50IiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoidGVuYW50Iiwic2Vzc2lvbkluZGV4Ijo2fSx7ImtleSI6Im9yZ2FuaXphdGlvbl9pZCIsInZhbHVlIjoiaWQiLCJlbmFibGVkIjp0cnVlLCJzZXNzaW9uVmFsdWUiOiJpZCIsInNlc3Npb25JbmRleCI6N30seyJrZXkiOiJkb21haW5faWQiLCJ2YWx1ZSI6ImlkIiwiZW5hYmxlZCI6dHJ1ZSwic2Vzc2lvblZhbHVlIjoiaWQiLCJzZXNzaW9uSW5kZXgiOjh9LHsia2V5IjoidXNlcl9ncm91cF9pZCIsInZhbHVlIjoiaWQiLCJlbmFibGVkIjp0cnVlLCJzZXNzaW9uVmFsdWUiOiJpZCIsInNlc3Npb25JbmRleCI6OX0seyJrZXkiOiJzZXJ2aWNlX25hbWUiLCJ2YWx1ZSI6Im5hbWUiLCJlbmFibGVkIjp0cnVlLCJzZXNzaW9uVmFsdWUiOiJuYW1lIiwic2Vzc2lvbkluZGV4IjoxMH1d"><img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style={{width: '128px', height: '32px' }}/>
+</a>