From 3d08263f3827a18df1192315688a3db3c2df190e Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 16 Apr 2024 16:29:27 -0500 Subject: [PATCH 1/2] fix(api): Update HTTP API landing page in Dedicated - Adds a custom short title field in OpenAPI info. - Uses the new field for nav menu item names. - Adds identifiers to avoid duplicate name warnings. - Cleans up variation in frontmatter. --- .../management/content/info.yml | 1 + .../v1-compatibility/content/info.yml | 1 + api-docs/cloud-dedicated/v2/content/info.yml | 1 + .../v1-compatibility/content/info.yml | 1 + api-docs/cloud-serverless/v2/content/info.yml | 1 + .../cloud/v1-compatibility/content/info.yml | 1 + api-docs/cloud/v2/content/info.yml | 1 + .../v1-compatibility/content/info.yml | 1 + api-docs/clustered/v2/content/info.yml | 1 + api-docs/generate-api-docs.sh | 24 ++++++++++++------- api-docs/v2/content/info.yml | 1 + api-docs/v2/v1-compatibility/content/info.yml | 3 ++- 12 files changed, 27 insertions(+), 10 deletions(-) diff --git a/api-docs/cloud-dedicated/management/content/info.yml b/api-docs/cloud-dedicated/management/content/info.yml index 070217abb..814a15f69 100644 --- a/api-docs/cloud-dedicated/management/content/info.yml +++ b/api-docs/cloud-dedicated/management/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB Cloud Dedicated Management API +x-influxdata-short-title: Management API summary: | The Management API for InfluxDB Cloud Dedicated provides a programmatic interface for managing an InfluxDB Cloud Dedicated instance. description: | diff --git a/api-docs/cloud-dedicated/v1-compatibility/content/info.yml b/api-docs/cloud-dedicated/v1-compatibility/content/info.yml index 19a7f036d..caa9d1643 100644 --- a/api-docs/cloud-dedicated/v1-compatibility/content/info.yml +++ b/api-docs/cloud-dedicated/v1-compatibility/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB v1 HTTP API for InfluxDB Cloud Dedicated +x-influxdata-short-title: v1 Compatibility API summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB v3 Cloud Dedicated database. description: | The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. diff --git a/api-docs/cloud-dedicated/v2/content/info.yml b/api-docs/cloud-dedicated/v2/content/info.yml index a1778e664..3b927a971 100644 --- a/api-docs/cloud-dedicated/v2/content/info.yml +++ b/api-docs/cloud-dedicated/v2/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB v2 HTTP API for InfluxDB Cloud Dedicated +x-influxdata-short-title: v2 API summary: The InfluxDB v2 HTTP API for InfluxDB Cloud Dedicated provides a v2-compatible programmatic interface for writing data stored in an InfluxDB Cloud Dedicated database. description: | diff --git a/api-docs/cloud-serverless/v1-compatibility/content/info.yml b/api-docs/cloud-serverless/v1-compatibility/content/info.yml index 9e0faafbc..1307b7422 100644 --- a/api-docs/cloud-serverless/v1-compatibility/content/info.yml +++ b/api-docs/cloud-serverless/v1-compatibility/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB v1 HTTP API for InfluxDB Cloud Serverless +x-influxdata-short-title: v1 Compatibility API summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB v3 Cloud Serverless bucket. description: | The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. diff --git a/api-docs/cloud-serverless/v2/content/info.yml b/api-docs/cloud-serverless/v2/content/info.yml index 293543ebf..5aab1cdbb 100644 --- a/api-docs/cloud-serverless/v2/content/info.yml +++ b/api-docs/cloud-serverless/v2/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB Cloud Serverless API Service +x-influxdata-short-title: v2 API summary: | The InfluxDB v2 HTTP API for InfluxDB Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB Cloud Serverless bucket. description: | diff --git a/api-docs/cloud/v1-compatibility/content/info.yml b/api-docs/cloud/v1-compatibility/content/info.yml index a74f1ce5f..07ae7e9e7 100644 --- a/api-docs/cloud/v1-compatibility/content/info.yml +++ b/api-docs/cloud/v1-compatibility/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB v1 HTTP API for InfluxDB Cloud +x-influxdata-short-title: v1 Compatibility API summary: The InfluxDB v1 compatibility API provides a programmatic interface for interactions with InfluxDB Cloud using InfluxDB v1-compatible endpoints. description: | The InfluxDB 1.x compatibility /write and /query endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. diff --git a/api-docs/cloud/v2/content/info.yml b/api-docs/cloud/v2/content/info.yml index 1e7aa0467..0504afa39 100644 --- a/api-docs/cloud/v2/content/info.yml +++ b/api-docs/cloud/v2/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB Cloud API Service +x-influxdata-short-title: v2 API summary: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with InfluxDB v2. description: | The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with InfluxDB v2. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints. diff --git a/api-docs/clustered/v1-compatibility/content/info.yml b/api-docs/clustered/v1-compatibility/content/info.yml index 97fcb5fb7..7fbb572ef 100644 --- a/api-docs/clustered/v1-compatibility/content/info.yml +++ b/api-docs/clustered/v1-compatibility/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB v1 HTTP API for InfluxDB Clustered +x-influxdata-short-title: v1 Compatibility API summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB v3 Clustered database. description: | The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. diff --git a/api-docs/clustered/v2/content/info.yml b/api-docs/clustered/v2/content/info.yml index 3fc47d703..f1f4be6d3 100644 --- a/api-docs/clustered/v2/content/info.yml +++ b/api-docs/clustered/v2/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB Clustered API Service +x-influxdata-short-title: v2 API summary: The InfluxDB v2 HTTP API for InfluxDB Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB Clustered database. description: | The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB v3 instance. diff --git a/api-docs/generate-api-docs.sh b/api-docs/generate-api-docs.sh index 6b3fc41a8..22d87c1e8 100755 --- a/api-docs/generate-api-docs.sh +++ b/api-docs/generate-api-docs.sh @@ -47,13 +47,11 @@ function generateHtml { menu="influxdb_$(echo $product | sed 's/\./_/g;s/-/_/g;')" # Extract the API name--for example, "management" from "management@v2". apiName=$(echo $api | sed 's/@.*//g;') - # Convert it to title case--for example, "Management". - apiTitle=$(echo $apiName \ - | awk '{print toupper(substr($1,1,1)) tolower(substr($1,2))}') # Extract the API version--for example, "v0" from "management@v0". version=$(echo $api | sed 's/.*@//g;') # Use the title and summary defined in the product API's info.yml file. title=$(yq '.title' $product/$apiName/content/info.yml) + menuTitle=$(yq '.x-influxdata-short-title' $product/$apiName/content/info.yml) description=$(yq '.summary' $product/$apiName/content/info.yml) # Define the file name for the Redoc HTML output. specbundle=redoc-static_index.html @@ -80,16 +78,19 @@ function generateHtml { --templateOptions.product="$product" \ --templateOptions.productName="$productName" - if [[ $version == "v1" ]]; then + if [[ $apiName == "v1-compatibility" ]]; then frontmatter="--- title: $title description: $description layout: api menu: $menu: - parent: $version compatibility - name: View $version compatibility API + parent: InfluxDB HTTP API + name: $menuTitle + identifier: api-reference-$apiName weight: 304 +aliases: + - /influxdb/$product/api/v1/ --- " elif [[ $version == "0" ]]; then @@ -102,7 +103,8 @@ weight: 102 menu: $menu: parent: InfluxDB HTTP API - name: Management API + name: $menuTitle + identifier: api-reference-$apiName --- " elif [[ $isDefault == true ]]; then @@ -113,7 +115,8 @@ layout: api menu: $menu: parent: InfluxDB HTTP API - name: $apiTitle API + name: $menuTitle + identifier: api-reference-$apiName weight: 102 aliases: - /influxdb/$product/api/ @@ -127,7 +130,8 @@ layout: api menu: $menu: parent: InfluxDB HTTP API - name: $apiTitle API + name: $menuTitle + identifier: api-reference-$apiName weight: 102 --- " @@ -156,6 +160,8 @@ weight: 102 fi } +# Use a combination of directory names and configuration files to build the API documentation. +# Each directory represents a product, and each product directory contains a configuration file that defines APIs and their spec file locations. function build { # Get the list of products from directory names products="$(ls -d -- */ | grep -v 'node_modules' | grep -v 'openapi')" diff --git a/api-docs/v2/content/info.yml b/api-docs/v2/content/info.yml index f381806c2..4a75f7efa 100644 --- a/api-docs/v2/content/info.yml +++ b/api-docs/v2/content/info.yml @@ -1,4 +1,5 @@ title: InfluxDB OSS API Service +x-influxdata-short-title: v2 API summary: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. description: | The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints. diff --git a/api-docs/v2/v1-compatibility/content/info.yml b/api-docs/v2/v1-compatibility/content/info.yml index 17ab99443..f897815d3 100644 --- a/api-docs/v2/v1-compatibility/content/info.yml +++ b/api-docs/v2/v1-compatibility/content/info.yml @@ -1,7 +1,8 @@ title: InfluxDB v1 HTTP API for InfluxDB v2 OSS +x-influxdata-short-title: v1 Compatibility API summary: The InfluxDB v1 compatibility API provides a programmatic interface for interactions with InfluxDB v2 using InfluxDB v1-compatible endpoints. description: | - The InfluxDB 1.x compatibility /write and /query endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. + The InfluxDB 1.x compatibility `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. This documentation is generated from the [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml). From fd73956bd4e7e13233a46401203110aa119efacd Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 16 Apr 2024 16:45:11 -0500 Subject: [PATCH 2/2] fix(api): fixes #5412. Updates API landing pages to include Management API for Cloud Dedicated and descriptions of v1 and v2 APIs for each product. --- .../cloud-dedicated/reference/api/_index.md | 35 ++++++++++++++----- .../cloud-serverless/reference/api/_index.md | 23 ++++++++---- .../clustered/reference/api/_index.md | 26 +++++++++----- content/influxdb/v2/api-guide/api_intro.md | 6 ++-- content/influxdb/v2/reference/api/_index.md | 30 ++++++++++------ 5 files changed, 84 insertions(+), 36 deletions(-) diff --git a/content/influxdb/cloud-dedicated/reference/api/_index.md b/content/influxdb/cloud-dedicated/reference/api/_index.md index 11d922f66..cd01fe9e8 100644 --- a/content/influxdb/cloud-dedicated/reference/api/_index.md +++ b/content/influxdb/cloud-dedicated/reference/api/_index.md @@ -1,22 +1,41 @@ --- title: InfluxDB HTTP API description: > - The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB. - Access the InfluxDB API using the `/api/v2/` endpoint or InfluxDB v1 endpoints. + The InfluxDB HTTP API provides a programmatic interface for interactions with + InfluxDB, such as writing and querying data, and managing an InfluxDB cluster. + Access the InfluxDB API using the `/api/v2/write`, InfluxDB v1, or + Management API endpoints for InfluxDB Cloud Dedicated. menu: influxdb_cloud_dedicated: parent: Reference name: InfluxDB HTTP API weight: 104 influxdb/cloud-dedicated/tags: [api] -aliases: - - /influxdb/cloud-dedicated/api/v1-compatibility/ --- -The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB. +The InfluxDB HTTP API provides a programmatic interface for interactions with +{{% product-name %}}, such as writing and querying data, and managing an InfluxDB cluster. -## InfluxDB HTTP API reference +Access the InfluxDB HTTP API using the `/api/v2/` endpoint, InfluxDB v1 endpoints, or +Management API endpoints for {{% product-name %}}. -InfluxDB Cloud Dedicated HTTP API reference +## InfluxDB v2 Compatibility API reference documentation -The API reference describes requests and responses for `/api/v2/` endpoints and v1 `/query` and `/write` endpoints. \ No newline at end of file +InfluxDB v2 API for {{% product-name %}} + +The API reference describes requests and responses for InfluxDB v2-compatible +endpoints that work with {{% product-name %}} and with InfluxDB 2.x client +libraries and third-party integrations. + +## InfluxDB v1 Compatibility API reference documentation + +InfluxDB v1 API for {{% product-name %}} + +The API reference describes requests and responses for InfluxDB v1-compatible `/write` and `/query` endpoints that work with {{% product-name %}} and with InfluxDB 1.x client libraries and third-party integrations. + +## InfluxDB Management API reference documentation + +InfluxDB Management API for {{% product-name %}} + +The API reference describes requests and responses for InfluxDB Management API endpoints. +The Management API lets cluster administrators manage resources such as databases, partitioning templates, and database tokens. diff --git a/content/influxdb/cloud-serverless/reference/api/_index.md b/content/influxdb/cloud-serverless/reference/api/_index.md index e41eee325..7f29a54c3 100644 --- a/content/influxdb/cloud-serverless/reference/api/_index.md +++ b/content/influxdb/cloud-serverless/reference/api/_index.md @@ -2,21 +2,30 @@ title: InfluxDB HTTP API description: > The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB. - Access the InfluxDB API using the `/api/v2/` endpoint or InfluxDB v1 endpoints. + Access the InfluxDB API using the `/api/v2/write` or InfluxDB v1 endpoints. menu: influxdb_cloud_serverless: parent: Reference name: InfluxDB HTTP API weight: 104 influxdb/cloud-serverless/tags: [api] -aliases: - - /influxdb/cloud-serverless/api/v1-compatibility/ --- -The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB. +The InfluxDB HTTP API provides a programmatic interface for interactions with +{{% product-name %}}, such as writing and querying data. -## InfluxDB HTTP API reference +Access the InfluxDB HTTP API using the `/api/v2/` or InfluxDB v1 endpoints. -InfluxDB Cloud Serverless HTTP API reference +## InfluxDB v2 Compatibility API reference documentation -The API reference describes requests and responses for `/api/v2/` endpoints and v1 `/query` and `/write` endpoints. +InfluxDB v2 API for {{% product-name %}} + +The API reference describes requests and responses for InfluxDB v2-compatible +endpoints that work with {{% product-name %}} and with InfluxDB 2.x client +libraries and third-party integrations. + +## InfluxDB v1 Compatibility API reference documentation + +InfluxDB v1 API for {{% product-name %}} + +The API reference describes requests and responses for InfluxDB v1-compatible `/write` and `/query` endpoints that work with {{% product-name %}} and with InfluxDB 1.x client libraries and third-party integrations. diff --git a/content/influxdb/clustered/reference/api/_index.md b/content/influxdb/clustered/reference/api/_index.md index f3e23e980..1ba05d8be 100644 --- a/content/influxdb/clustered/reference/api/_index.md +++ b/content/influxdb/clustered/reference/api/_index.md @@ -1,22 +1,32 @@ --- title: InfluxDB HTTP API description: > - The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB. - Access the InfluxDB API using the `/api/v2/` endpoint or InfluxDB v1 endpoints. + The InfluxDB HTTP API provides a programmatic interface for interactions with + InfluxDB, such as writing and querying data. + Access the InfluxDB API using the `/api/v2/write` or InfluxDB v1 endpoints. menu: influxdb_clustered: parent: Reference name: InfluxDB HTTP API weight: 104 influxdb/clustered/tags: [api] -aliases: - - /influxdb/clustered/api/v1-compatibility/ --- -The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB. +The InfluxDB HTTP API provides a programmatic interface for interactions with +{{% product-name %}}, such as writing and querying data. -## InfluxDB HTTP API reference +Access the InfluxDB HTTP API using the `/api/v2/` or InfluxDB v1 endpoints. -InfluxDB Clustered HTTP API reference +## InfluxDB v2 Compatibility API reference documentation -The API reference describes requests and responses for `/api/v2/` endpoints and v1 `/query` and `/write` endpoints. \ No newline at end of file +InfluxDB v2 API for {{% product-name %}} + +The API reference describes requests and responses for InfluxDB v2-compatible +endpoints that work with {{% product-name %}} and with InfluxDB 2.x client +libraries and third-party integrations. + +## InfluxDB v1 Compatibility API reference documentation + +InfluxDB v1 API for {{% product-name %}} + +The API reference describes requests and responses for InfluxDB v1-compatible `/write` and `/query` endpoints that work with {{% product-name %}} and with InfluxDB 1.x client libraries and third-party integrations. diff --git a/content/influxdb/v2/api-guide/api_intro.md b/content/influxdb/v2/api-guide/api_intro.md index 085fe98f8..b02bb0496 100644 --- a/content/influxdb/v2/api-guide/api_intro.md +++ b/content/influxdb/v2/api-guide/api_intro.md @@ -14,12 +14,12 @@ influxdb/cloud/tags: [api] InfluxDB offers a rich API and [client libraries](/influxdb/v2/api-guide/client-libraries) ready to integrate with your application. Use popular tools like Curl and [Postman](/influxdb/v2/api-guide/postman) for rapidly testing API requests. -This section will guide you through the most commonly used API methods. +This section guides you through the most commonly used API methods. -For detailed documentation on the entire API, see [InfluxDBv2 API Reference](/influxdb/v2/reference/api/#influxdb-v2-api-documentation). +For detailed documentation on the entire API, see the [InfluxDB v2 API Reference](/influxdb/v2/reference/api/#influxdb-v2-api-documentation). {{% note %}} -If you need to use InfluxDB {{< current-version >}} with **InfluxDB 1.x** API clients and integrations, see the [1.x compatibility API](/influxdb/v2/reference/api/influxdb-1x/). +If you need to use InfluxDB {{< current-version >}} with **InfluxDB 1.x** API clients and integrations, see the [1.x compatibility API](/influxdb/v2/reference/api/#influxdb-v1-compatibility-api-reference-documentation). {{% /note %}} ## Bootstrap your application diff --git a/content/influxdb/v2/reference/api/_index.md b/content/influxdb/v2/reference/api/_index.md index 62c45b3db..3e873d6ad 100644 --- a/content/influxdb/v2/reference/api/_index.md +++ b/content/influxdb/v2/reference/api/_index.md @@ -1,8 +1,9 @@ --- title: InfluxDB v2 API description: > - The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. - Access the InfluxDB API using the `/api/v2/` endpoint. + The InfluxDB HTTP API provides a programmatic interface for interactions with InfluxDB, such as writing and querying data, + and managing resources within an InfluxDB instance. + Access the InfluxDB API using the `/api/v2/` or InfluxDB v1 endpoints. menu: influxdb_v2: parent: Reference @@ -12,21 +13,30 @@ aliases: - /influxdb/v2/concepts/api/ --- -The InfluxDB v2 API provides a programmatic interface for interactions with InfluxDB. -Access the InfluxDB API using the `/api/v2/` endpoint. +The InfluxDB v2 API provides a programmatic interface for interactions such as writing and querying data, and managing resources in {{% product-name %}}. + +Access the InfluxDB HTTP API using the `/api/v2/` endpoint or InfluxDB v1 endpoints +for {{% product-name %}} ## InfluxDB v2 API documentation -InfluxDB OSS {{< current-version >}} API documentation + +InfluxDB {{< current-version >}} API + +{{% oss-only %}} #### View InfluxDB API documentation locally + InfluxDB API documentation is built into the `influxd` service and represents -the API specific to the current version of InfluxDB. +the API specific to your version of InfluxDB. To view the API documentation locally, [start InfluxDB](/influxdb/v2/get-started/#start-influxdb) and visit the `/docs` endpoint in a browser ([localhost:8086/docs](http://localhost:8086/docs)). -## InfluxDB v1 compatibility API documentation -The InfluxDB v2 API includes [InfluxDB 1.x compatibility endpoints](/influxdb/v2/reference/api/influxdb-1x/) +{{% /oss-only %}} + +## InfluxDB v1 Compatibility API reference documentation + +InfluxDB v1 API for {{% product-name %}} + +The InfluxDB HTTP API includes [InfluxDB v1 compatibility endpoints](/influxdb/v2/reference/api/influxdb-1x/) that work with InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others. - -View full v1 compatibility API documentation