feat(api-docs): extract api-docs changes from feat-api-uplift
Extract all api-docs/ changes from feat-api-uplift into a standalone branch for independent testing and merging to master. Changes include: - Updated generation scripts (generate-openapi-articles.ts, openapi-paths-to-hugo-data/index.ts) for Hugo-native templates - Removed dead x-tagGroups infrastructure (decorator, config files) - Updated Core and Enterprise specs with tag descriptions, x-related links, and Cache Data tag split - Added v1 product configs and specs (OSS v1, Enterprise v1) - Updated getswagger.sh for renamed spec files - Updated generate-api-docs.sh with clean regeneration supportpull/6942/head
Jason Stirnaman
parent
e1e7e22242
commit
914380ea54
|
|
@ -48,6 +48,7 @@
|
|||
```
|
||||
|
||||
3. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
|
||||
|
||||
4. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
|
||||
|
||||
## Update API docs for an InfluxDB OSS release
|
||||
|
|
@ -106,8 +107,8 @@
|
|||
# Copy the old version directory to a directory for the new version:
|
||||
cp -r v2.2 v2.3
|
||||
```
|
||||
|
||||
8. In your editor, update custom content files in NEW_VERSION/content.
|
||||
|
||||
8. In your editor, update custom content files in NEW\_VERSION/content.
|
||||
|
||||
9. Enter the following commands into your terminal to fetch and process the contracts:
|
||||
|
||||
|
|
@ -117,6 +118,7 @@
|
|||
```
|
||||
|
||||
10. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
|
||||
|
||||
11. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
|
||||
|
||||
## Update API docs for OSS spec changes between releases
|
||||
|
|
@ -142,6 +144,8 @@ Follow these steps to update OSS API docs between version releases--for example,
|
|||
git cherry-pick [COMMIT_SHAs]
|
||||
git push -f origin docs-release/influxdb-oss
|
||||
|
||||
```
|
||||
|
||||
4. Go into your `docs-v2` directory and create a branch for your changes--for example:
|
||||
|
||||
```sh
|
||||
|
|
@ -165,6 +169,7 @@ Follow these steps to update OSS API docs between version releases--for example,
|
|||
```
|
||||
|
||||
7. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
|
||||
|
||||
8. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
|
||||
|
||||
## Generate InfluxDB API docs
|
||||
|
|
@ -197,7 +202,7 @@ The script uses `npx` to download and execute the Redocly CLI.
|
|||
|
||||
If `npx` returns errors, [download](https://nodejs.org/en/) and run a recent version of the Node.js installer for your OS.
|
||||
|
||||
2. To generate API docs for _all_ InfluxDB versions in `./openapi`, enter the following command into your terminal:
|
||||
2. To generate API docs for *all* InfluxDB versions in `./openapi`, enter the following command into your terminal:
|
||||
|
||||
```sh
|
||||
sh generate-api-docs.sh
|
||||
|
|
@ -239,9 +244,9 @@ We regenerate API reference docs from `influxdata/openapi`
|
|||
|
||||
### InfluxDB OSS v2 version
|
||||
|
||||
Given that
|
||||
`influxdata/openapi` **master** may contain OSS spec changes not implemented
|
||||
in the current OSS release, we (Docs team) maintain a release branch, `influxdata/openapi`
|
||||
Given that
|
||||
`influxdata/openapi` **master** may contain OSS spec changes not implemented
|
||||
in the current OSS release, we (Docs team) maintain a release branch, `influxdata/openapi`
|
||||
**docs-release/influxdb-oss**, used to generate OSS reference docs.
|
||||
|
||||
### How to find the API spec used by an InfluxDB OSS version
|
||||
|
|
@ -249,7 +254,7 @@ We regenerate API reference docs from `influxdata/openapi`
|
|||
`influxdata/openapi` does not version the InfluxData API.
|
||||
To find the `influxdata/openapi` commit SHA used in a specific version of InfluxDB OSS,
|
||||
see `/scripts/fetch-swagger.sh` in `influxdata/influxdb`--for example,
|
||||
for the `influxdata/openapi` commit used in OSS v2.2.0, see https://github.com/influxdata/influxdb/blob/v2.2.0/scripts/fetch-swagger.sh#L13=.
|
||||
for the `influxdata/openapi` commit used in OSS v2.2.0, see <https://github.com/influxdata/influxdb/blob/v2.2.0/scripts/fetch-swagger.sh#L13=>.
|
||||
For convenience, we tag `influxdata/influxdb` (OSS) release points in `influxdata/openapi` as
|
||||
`influxdb-oss-v[OSS_VERSION]`. See <https://github.com/influxdata/openapi/tags>.
|
||||
|
||||
|
|
@ -281,16 +286,17 @@ To add new YAML files for other nodes in the contracts, follow these steps:
|
|||
|
||||
`@redocly/cli` also provides some [built-in decorators](https://redocly.com/docs/cli/decorators/)
|
||||
that you can configure in `.redocly` without having to write JavaScript.
|
||||
|
||||
### How to add tag content or describe a group of paths
|
||||
|
||||
In API reference docs, we use OpenAPI `tags` elements for navigation,
|
||||
the `x-traitTag` vendor extension for providing custom content, and the `x-tagGroups` vendor extension
|
||||
for grouping tags in navigation.
|
||||
|
||||
| Example | OpenAPI field | |
|
||||
|:-------------------------------------------------------------------------------------------------------|-------------------------------------------------------|--------------------------------------------|
|
||||
| [Add supplementary documentation](https://docs.influxdata.com/influxdb/cloud/api/#tag/Quick-start) | `tags: [ { name: 'Quick start', x-traitTag: true } ]` | [Source](https://github.com/influxdata/openapi/master/src/cloud/tags.yml) |
|
||||
| Group tags in navigation | `x-tagGroups: [ { name: 'All endpoints', tags: [...], ...} ]` | [Source](https://github.com/influxdata/docs-v2/blob/da6c2e467de7212fc2197dfe0b87f0f0296688ee/api-docs/cloud-iox/content/tag-groups.yml)) |
|
||||
| Example | OpenAPI field | |
|
||||
| :------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Add supplementary documentation](https://docs.influxdata.com/influxdb/cloud/api/#tag/Quick-start) | `tags: [ { name: 'Quick start', x-traitTag: true } ]` | [Source](https://github.com/influxdata/openapi/master/src/cloud/tags.yml) |
|
||||
| Group tags in navigation | `x-tagGroups: [ { name: 'All endpoints', tags: [...], ...} ]` | [Source](https://github.com/influxdata/docs-v2/blob/da6c2e467de7212fc2197dfe0b87f0f0296688ee/api-docs/cloud-iox/content/tag-groups.yml)) |
|
||||
|
||||
#### Add and update x-tagGroups
|
||||
|
||||
|
|
@ -302,6 +308,47 @@ those tags.
|
|||
If you assign an empty array(`[]`) to the `All endpoints` x-tagGroup in `PLATFORM/content/tag-groups.yml`,
|
||||
the decorator replaces the empty array with the list of tags from all Operations in the spec.
|
||||
|
||||
## Documentation links in OpenAPI specs
|
||||
|
||||
Use the `/influxdb/version/` placeholder when including InfluxDB links in OpenAPI spec description and summary fields.
|
||||
The build process automatically transforms these placeholders to product-specific paths based on the spec file location.
|
||||
|
||||
### Writing links
|
||||
|
||||
```yaml
|
||||
# In api-docs/influxdb3/core/openapi/ref.yml
|
||||
info:
|
||||
description: |
|
||||
See [authentication](/influxdb/version/api/authentication/) for details.
|
||||
Related: [tokens](/influxdb/version/admin/tokens/)
|
||||
```
|
||||
|
||||
After build, these become:
|
||||
|
||||
- `/influxdb3/core/api/authentication/`
|
||||
- `/influxdb3/core/admin/tokens/`
|
||||
|
||||
### How it works
|
||||
|
||||
The product path is derived from the spec file location:
|
||||
|
||||
- `api-docs/influxdb3/core/...` → `/influxdb3/core`
|
||||
- `api-docs/influxdb3/enterprise/...` → `/influxdb3/enterprise`
|
||||
- `api-docs/influxdb/v2/...` → `/influxdb/v2`
|
||||
|
||||
Only `description` and `summary` fields are transformed.
|
||||
Explicit cross-product links (e.g., `/telegraf/v1/plugins/`) remain unchanged.
|
||||
|
||||
### Link validation
|
||||
|
||||
Run with the `--validate-links` flag to check for broken links:
|
||||
|
||||
```bash
|
||||
yarn build:api-docs --validate-links
|
||||
```
|
||||
|
||||
This validates that transformed links point to existing Hugo content files and warns about any broken links.
|
||||
|
||||
## How to test your spec or API reference changes
|
||||
|
||||
You can use `getswagger.sh` to fetch contracts from any URL.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,10 @@
|
|||
plugins:
|
||||
- '../../openapi/plugins/docs-plugin.cjs'
|
||||
extends:
|
||||
- recommended
|
||||
- docs/all
|
||||
x-influxdata-product-name: InfluxDB Enterprise v1
|
||||
|
||||
apis:
|
||||
v1@1:
|
||||
root: v1/ref.yml
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
title: InfluxDB Enterprise v1 HTTP API
|
||||
x-influxdata-short-title: InfluxDB Enterprise v1 API
|
||||
x-influxdata-short-description: >-
|
||||
The InfluxDB Enterprise v1 HTTP API provides a programmatic interface for writing,
|
||||
querying, and managing InfluxDB Enterprise v1 clusters.
|
||||
version: 1.11.6
|
||||
description: |
|
||||
The InfluxDB Enterprise v1 HTTP API provides a simple way to interact with the database.
|
||||
It uses HTTP response codes, authentication with username and password credentials
|
||||
or API tokens, and JSON-formatted response data.
|
||||
|
||||
## Cluster Features
|
||||
|
||||
InfluxDB Enterprise includes additional parameters for cluster operations:
|
||||
- **Write Consistency**: Control write consistency across cluster nodes
|
||||
|
||||
## Authentication
|
||||
|
||||
InfluxDB Enterprise v1 supports multiple authentication methods:
|
||||
|
||||
- **Basic Authentication**: Use HTTP Basic Auth with username and password
|
||||
- **Query String Authentication**: Pass `u` (username) and `p` (password) as query parameters
|
||||
- **Token Authentication** (v2-compatible): Use `Authorization: Token username:password` header
|
||||
|
||||
Authentication is optional unless [enabled in the configuration](/enterprise_influxdb/v1/administration/authentication_and_authorization/).
|
||||
license:
|
||||
name: Proprietary
|
||||
url: https://www.influxdata.com/legal/slsa/
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
- url: http://localhost:8086
|
||||
description: Local InfluxDB Enterprise data node
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -187,3 +187,9 @@ function build {
|
|||
}
|
||||
|
||||
build
|
||||
|
||||
# Generate tag-based article data and content pages
|
||||
echo "Generating OpenAPI article data..."
|
||||
cd ..
|
||||
node api-docs/scripts/dist/generate-openapi-articles.js
|
||||
cd api-docs
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ function showHelp {
|
|||
subcommand=$1
|
||||
|
||||
case "$subcommand" in
|
||||
cloud-dedicated-v2|cloud-dedicated-management|cloud-serverless-v2|clustered-management|clustered-v2|cloud-v2|v2|v1-compat|core-v3|enterprise-v3|all)
|
||||
cloud-dedicated-v2|cloud-dedicated-management|cloud-serverless-v2|clustered-management|clustered-v2|cloud-v2|v2|v1-compat|oss-v1|enterprise-v1|core-v3|enterprise-v3|all)
|
||||
product=$1
|
||||
shift
|
||||
|
||||
|
|
@ -215,7 +215,7 @@ function updateClusteredV2 {
|
|||
}
|
||||
|
||||
function updateCoreV3 {
|
||||
outFile="influxdb3/core/v3/ref.yml"
|
||||
outFile="influxdb3/core/v3/influxdb3-core-openapi.yaml"
|
||||
if [[ -z "$baseUrl" ]];
|
||||
then
|
||||
echo "Using existing $outFile"
|
||||
|
|
@ -227,7 +227,7 @@ function updateCoreV3 {
|
|||
}
|
||||
|
||||
function updateEnterpriseV3 {
|
||||
outFile="influxdb3/enterprise/v3/ref.yml"
|
||||
outFile="influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml"
|
||||
if [[ -z "$baseUrl" ]];
|
||||
then
|
||||
echo "Using existing $outFile"
|
||||
|
|
@ -273,6 +273,18 @@ function updateV1Compat {
|
|||
postProcess $outFile 'influxdb3/clustered/.config.yml' 'v1-compatibility'
|
||||
}
|
||||
|
||||
function updateOSSV1 {
|
||||
outFile="influxdb/v1/v1/ref.yml"
|
||||
echo "Processing $outFile with decorators"
|
||||
postProcess $outFile 'influxdb/v1/.config.yml' 'v1@1'
|
||||
}
|
||||
|
||||
function updateEnterpriseV1 {
|
||||
outFile="enterprise_influxdb/v1/v1/ref.yml"
|
||||
echo "Processing $outFile with decorators"
|
||||
postProcess $outFile 'enterprise_influxdb/v1/.config.yml' 'v1@1'
|
||||
}
|
||||
|
||||
UPDATE_OPTIONS="--fail"
|
||||
|
||||
if [ ! -z ${verbose} ];
|
||||
|
|
@ -312,6 +324,12 @@ then
|
|||
elif [ "$product" = "v1-compat" ];
|
||||
then
|
||||
updateV1Compat
|
||||
elif [ "$product" = "oss-v1" ];
|
||||
then
|
||||
updateOSSV1
|
||||
elif [ "$product" = "enterprise-v1" ];
|
||||
then
|
||||
updateEnterpriseV1
|
||||
elif [ "$product" = "all" ];
|
||||
then
|
||||
updateCloudV2
|
||||
|
|
@ -322,8 +340,10 @@ then
|
|||
updateCoreV3
|
||||
updateEnterpriseV3
|
||||
updateOSSV2
|
||||
updateOSSV1
|
||||
updateEnterpriseV1
|
||||
updateV1Compat
|
||||
else
|
||||
echo "Provide a product argument: cloud-v2, cloud-serverless-v2, cloud-dedicated-v2, cloud-dedicated-management, clustered-management, clustered-v2, core-v3, enterprise-v3, v2, v1-compat, or all."
|
||||
echo "Provide a product argument: cloud-v2, cloud-serverless-v2, cloud-dedicated-v2, cloud-dedicated-management, clustered-management, clustered-v2, core-v3, enterprise-v3, v2, oss-v1, enterprise-v1, v1-compat, or all."
|
||||
showHelp
|
||||
fi
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
- Quick start
|
||||
- Authentication
|
||||
- Supported operations
|
||||
- Headers
|
||||
- Pagination
|
||||
- Response codes
|
||||
- name: All endpoints
|
||||
tags: []
|
||||
|
|
@ -99,7 +99,6 @@ tags:
|
|||
x-traitTag: true
|
||||
- name: Config
|
||||
- name: Dashboards
|
||||
- name: Data I/O endpoints
|
||||
- description: |
|
||||
The InfluxDB 1.x data model includes [databases](/influxdb/cloud/reference/glossary/#database)
|
||||
and [retention policies](/influxdb/cloud/reference/glossary/#retention-policy-rp).
|
||||
|
|
@ -126,7 +125,7 @@ tags:
|
|||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `Authorization` | string | The authorization scheme and credential. |
|
||||
| `Authorization` | string | The [authorization scheme and credential](/influxdb/version/api/authentication/). |
|
||||
| `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. |
|
||||
| `Content-Type` | string | The format of the data in the request body. |
|
||||
name: Headers
|
||||
|
|
@ -208,13 +207,33 @@ tags:
|
|||
- name: Ping
|
||||
- description: |
|
||||
Retrieve data, analyze queries, and get query suggestions.
|
||||
name: Query
|
||||
name: Query data
|
||||
- description: |
|
||||
See the [**API Quick Start**](/influxdb/cloud/api-guide/api_intro/)
|
||||
to get up and running authenticating with tokens, writing to buckets, and querying data.
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
[**InfluxDB API client libraries**](/influxdb/cloud/api-guide/client-libraries/)
|
||||
are available for popular languages and ready to import into your application.
|
||||
1. Create an API token to authorize API requests.
|
||||
Use the InfluxDB Cloud UI or `POST /api/v2/authorizations`.
|
||||
|
||||
2. Write data to InfluxDB Cloud.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cloud2.influxdata.com/api/v2/write?org=ORG_NAME&bucket=BUCKET_NAME&precision=ns" \
|
||||
--header "Authorization: Token API_TOKEN" \
|
||||
--data-raw "home,room=Kitchen temp=72.0
|
||||
home,room=Living\ Room temp=71.5"
|
||||
```
|
||||
|
||||
3. Query data using Flux.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cloud2.influxdata.com/api/v2/query?org=ORG_NAME" \
|
||||
--header "Authorization: Token API_TOKEN" \
|
||||
--header "Content-Type: application/vnd.flux" \
|
||||
--data 'from(bucket: "BUCKET_NAME") |> range(start: -1h)'
|
||||
```
|
||||
|
||||
For more information, see the
|
||||
[Get started](/influxdb/cloud/get-started/) guide.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- name: Resources
|
||||
|
|
@ -326,7 +345,7 @@ tags:
|
|||
- name: Views
|
||||
- description: |
|
||||
Write time series data to [buckets](/influxdb/cloud/reference/glossary/#bucket).
|
||||
name: Write
|
||||
name: Write data
|
||||
paths:
|
||||
/api/v2:
|
||||
get:
|
||||
|
|
@ -4008,7 +4027,6 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Delete data
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Delete
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
|
|
@ -6186,8 +6204,7 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Query data
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
lang: Shell
|
||||
|
|
@ -6332,7 +6349,7 @@ paths:
|
|||
type: string
|
||||
summary: Analyze a Flux query
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: 'cURL: Analyze a Flux query'
|
||||
lang: Shell
|
||||
|
|
@ -6777,7 +6794,7 @@ paths:
|
|||
description: Internal server error.
|
||||
summary: Generate a query Abstract Syntax Tree (AST)
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: 'cURL: Analyze and generate AST for the query'
|
||||
lang: Shell
|
||||
|
|
@ -7441,7 +7458,7 @@ paths:
|
|||
description: Internal server error.
|
||||
summary: List Flux query suggestions
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
lang: Shell
|
||||
|
|
@ -7513,7 +7530,7 @@ paths:
|
|||
The value passed for _`name`_ may have been misspelled.
|
||||
summary: Retrieve a query suggestion for a branching suggestion
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
lang: Shell
|
||||
|
|
@ -7639,7 +7656,6 @@ paths:
|
|||
description: Unexpected error.
|
||||
summary: List scripts
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Invokable Scripts
|
||||
x-codeSamples:
|
||||
- label: 'cURL: retrieves the first 100 scripts.'
|
||||
|
|
@ -7835,7 +7851,6 @@ paths:
|
|||
description: Internal server error.
|
||||
summary: Retrieve a script
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Invokable Scripts
|
||||
patch:
|
||||
description: |
|
||||
|
|
@ -8048,7 +8063,6 @@ paths:
|
|||
description: Unexpected error.
|
||||
summary: Invoke a script
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Invokable Scripts
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
|
|
@ -8935,7 +8949,6 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: List all tasks
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Tasks
|
||||
x-codeSamples:
|
||||
- label: 'cURL: all tasks, basic output'
|
||||
|
|
@ -9054,7 +9067,6 @@ paths:
|
|||
description: Unexpected error
|
||||
summary: Create a task
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Tasks
|
||||
x-codeSamples:
|
||||
- label: 'cURL: create a Flux script task'
|
||||
|
|
@ -9161,7 +9173,6 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Retrieve a task
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Tasks
|
||||
patch:
|
||||
description: |
|
||||
|
|
@ -9803,7 +9814,6 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Start a task run, overriding the schedule
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Tasks
|
||||
/api/v2/tasks/{taskID}/runs/{runID}:
|
||||
delete:
|
||||
|
|
@ -11832,8 +11842,7 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Write data
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Write
|
||||
- Write data
|
||||
/legacy/authorizations:
|
||||
get:
|
||||
operationId: GetLegacyAuthorizations
|
||||
|
|
@ -19069,6 +19078,36 @@ components:
|
|||
in: header
|
||||
name: Authorization
|
||||
type: apiKey
|
||||
QuerystringAuthentication:
|
||||
description: |
|
||||
Use the query string authentication scheme with InfluxDB v1-compatible API operations.
|
||||
Pass your InfluxDB Cloud email address and API token as query parameters using `u` for username and `p` for password (API token).
|
||||
|
||||
### Syntax
|
||||
|
||||
`?u=EMAIL_ADDRESS&p=INFLUX_API_TOKEN`
|
||||
|
||||
### Example
|
||||
|
||||
```sh
|
||||
curl --get "INFLUX_URL/query" \
|
||||
--data-urlencode "u=EMAIL_ADDRESS" \
|
||||
--data-urlencode "p=INFLUX_API_TOKEN" \
|
||||
--data-urlencode "q=SHOW DATABASES"
|
||||
```
|
||||
|
||||
Replace the following:
|
||||
|
||||
- *`INFLUX_URL`*: your InfluxDB Cloud URL
|
||||
- *`EMAIL_ADDRESS`*: your InfluxDB Cloud email address
|
||||
- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token)
|
||||
|
||||
> [!Warning]
|
||||
> Query string authentication exposes your credentials in the URL and server logs.
|
||||
> Use [Token authentication](#section/Authentication/TokenAuthentication) for production environments.
|
||||
in: query
|
||||
name: u
|
||||
type: apiKey
|
||||
x-tagGroups:
|
||||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
|
|
@ -19099,7 +19138,7 @@ x-tagGroups:
|
|||
- NotificationRules
|
||||
- Organizations
|
||||
- Ping
|
||||
- Query
|
||||
- Query data
|
||||
- Resources
|
||||
- Routes
|
||||
- Rules
|
||||
|
|
@ -19115,4 +19154,4 @@ x-tagGroups:
|
|||
- Users
|
||||
- Variables
|
||||
- Views
|
||||
- Write
|
||||
- Write data
|
||||
|
|
|
|||
|
|
@ -0,0 +1,10 @@
|
|||
plugins:
|
||||
- '../../openapi/plugins/docs-plugin.cjs'
|
||||
extends:
|
||||
- recommended
|
||||
- docs/all
|
||||
x-influxdata-product-name: InfluxDB OSS v1
|
||||
|
||||
apis:
|
||||
v1@1:
|
||||
root: v1/ref.yml
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
title: InfluxDB v1 HTTP API
|
||||
x-influxdata-short-title: InfluxDB v1 API
|
||||
x-influxdata-short-description: >-
|
||||
The InfluxDB v1 HTTP API provides a programmatic interface for writing,
|
||||
querying, and managing InfluxDB v1 databases.
|
||||
version: 1.8.10
|
||||
description: |
|
||||
The InfluxDB v1 HTTP API provides a simple way to interact with the database.
|
||||
It uses HTTP response codes, authentication with username and password credentials
|
||||
or API tokens, and JSON-formatted response data.
|
||||
|
||||
## InfluxDB 3 Compatibility
|
||||
|
||||
InfluxDB 3 supports the v1 `/write` and `/query` HTTP API endpoints.
|
||||
If you're getting started with InfluxDB v1, we recommend using the
|
||||
InfluxDB v1 client libraries and InfluxQL for future compatibility.
|
||||
|
||||
## Authentication
|
||||
|
||||
InfluxDB v1 supports two authentication methods:
|
||||
|
||||
- **Basic Authentication**: Use HTTP Basic Auth with username and password
|
||||
- **Query String Authentication**: Pass `u` (username) and `p` (password) as query parameters
|
||||
- **Token Authentication** (v2-compatible): Use `Authorization: Token username:password` header
|
||||
|
||||
Authentication is optional unless [enabled in the configuration](/influxdb/v1/administration/authentication_and_authorization/).
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
- url: http://localhost:8086
|
||||
description: Local InfluxDB instance
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,11 +0,0 @@
|
|||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
- Quick start
|
||||
- Authentication
|
||||
- Supported operations
|
||||
- Headers
|
||||
- Pagination
|
||||
- Response codes
|
||||
- Compatibility endpoints
|
||||
- name: All endpoints
|
||||
tags: []
|
||||
|
|
@ -91,16 +91,13 @@ tags:
|
|||
x-traitTag: true
|
||||
- name: Compatibility endpoints
|
||||
description: |
|
||||
InfluxDB v2 provides a v1-compatible API for backward compatibility with InfluxDB 1.x clients and integrations.
|
||||
InfluxDB v2 provides v1-compatible API endpoints for backward compatibility with InfluxDB 1.x clients and integrations.
|
||||
|
||||
Use these endpoints with InfluxDB 1.x client libraries and third-party integrations such as Grafana, Telegraf, and other tools designed for InfluxDB 1.x. The compatibility layer maps InfluxDB 1.x concepts (databases, retention policies) to InfluxDB v2 resources (buckets, organizations) through database retention policy (DBRP) mappings.
|
||||
Use these endpoints with InfluxDB 1.x client libraries and third-party integrations such as Grafana, Telegraf, and other tools designed for InfluxDB 1.x.
|
||||
|
||||
- [Write data (v1-compatible)](#tag/Write-data-(v1-compatible))
|
||||
- [Query data using InfluxQL (v1-compatible)](#tag/Query-data-(v1-compatible))
|
||||
- [Manage v1-compatible users and permissions](#tag/Authorizations-(v1-compatible))
|
||||
The compatibility layer maps InfluxDB 1.x concepts (databases, retention policies) to InfluxDB v2 resources (buckets, organizations) through database retention policy (DBRP) mappings.
|
||||
- name: Config
|
||||
- name: Dashboards
|
||||
- name: Data I/O endpoints
|
||||
- description: |
|
||||
The InfluxDB 1.x data model includes [databases](/influxdb/v2/reference/glossary/#database)
|
||||
and [retention policies](/influxdb/v2/reference/glossary/#retention-policy-rp).
|
||||
|
|
@ -142,7 +139,7 @@ tags:
|
|||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `Authorization` | string | The authorization scheme and credential. |
|
||||
| `Authorization` | string | The [authorization scheme and credential](/influxdb/version/api/authentication/). |
|
||||
| `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. |
|
||||
| `Content-Type` | string | The format of the data in the request body. |
|
||||
name: Headers
|
||||
|
|
@ -200,14 +197,40 @@ tags:
|
|||
- name: Ping
|
||||
- description: |
|
||||
Retrieve data, analyze queries, and get query suggestions.
|
||||
name: Query
|
||||
name: Query data
|
||||
- name: Query data (v1-compatible)
|
||||
- description: |
|
||||
See the [**API Quick Start**](/influxdb/v2/api-guide/api_intro/)
|
||||
to get up and running authenticating with tokens, writing to buckets, and querying data.
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
[**InfluxDB API client libraries**](/influxdb/v2/api-guide/client-libraries/)
|
||||
are available for popular languages and ready to import into your application.
|
||||
1. Create an API token to authorize API requests.
|
||||
Use the InfluxDB UI or `POST /api/v2/authorizations`.
|
||||
|
||||
2. Check the status of the InfluxDB server.
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8086/health"
|
||||
```
|
||||
|
||||
3. Write data to InfluxDB.
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8086/api/v2/write?org=ORG_NAME&bucket=BUCKET_NAME&precision=ns" \
|
||||
--header "Authorization: Token API_TOKEN" \
|
||||
--data-raw "home,room=Kitchen temp=72.0
|
||||
home,room=Living\ Room temp=71.5"
|
||||
```
|
||||
|
||||
4. Query data using Flux.
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8086/api/v2/query?org=ORG_NAME" \
|
||||
--header "Authorization: Token API_TOKEN" \
|
||||
--header "Content-Type: application/vnd.flux" \
|
||||
--data 'from(bucket: "BUCKET_NAME") |> range(start: -1h)'
|
||||
```
|
||||
|
||||
For more information, see the
|
||||
[Get started](/influxdb/v2/get-started/) guide.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- name: Ready
|
||||
|
|
@ -321,7 +344,7 @@ tags:
|
|||
- name: Views
|
||||
- description: |
|
||||
Write time series data to [buckets](/influxdb/v2/reference/glossary/#bucket).
|
||||
name: Write
|
||||
name: Write data
|
||||
- name: Write data (v1-compatible)
|
||||
paths:
|
||||
/api/v2:
|
||||
|
|
@ -4490,7 +4513,6 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Delete data
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Delete
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
|
|
@ -6690,8 +6712,7 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Query data
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
lang: Shell
|
||||
|
|
@ -6836,7 +6857,7 @@ paths:
|
|||
type: string
|
||||
summary: Analyze a Flux query
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: 'cURL: Analyze a Flux query'
|
||||
lang: Shell
|
||||
|
|
@ -7281,7 +7302,7 @@ paths:
|
|||
description: Internal server error.
|
||||
summary: Generate a query Abstract Syntax Tree (AST)
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: 'cURL: Analyze and generate AST for the query'
|
||||
lang: Shell
|
||||
|
|
@ -7945,7 +7966,7 @@ paths:
|
|||
description: Internal server error.
|
||||
summary: List Flux query suggestions
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
lang: Shell
|
||||
|
|
@ -8017,7 +8038,7 @@ paths:
|
|||
The value passed for _`name`_ may have been misspelled.
|
||||
summary: Retrieve a query suggestion for a branching suggestion
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
lang: Shell
|
||||
|
|
@ -9930,7 +9951,6 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: List tasks
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Tasks
|
||||
x-codeSamples:
|
||||
- label: 'cURL: all tasks, basic output'
|
||||
|
|
@ -10001,7 +10021,6 @@ paths:
|
|||
description: Unexpected error
|
||||
summary: Create a task
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Tasks
|
||||
x-codeSamples:
|
||||
- label: 'cURL: create a task'
|
||||
|
|
@ -10086,7 +10105,6 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Retrieve a task
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Tasks
|
||||
patch:
|
||||
description: |
|
||||
|
|
@ -10680,7 +10698,6 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Start a task run, overriding the schedule
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Tasks
|
||||
/api/v2/tasks/{taskID}/runs/{runID}:
|
||||
delete:
|
||||
|
|
@ -12809,8 +12826,7 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Write data
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Write
|
||||
- Write data
|
||||
/legacy/authorizations:
|
||||
get:
|
||||
operationId: GetLegacyAuthorizations
|
||||
|
|
@ -20173,6 +20189,36 @@ components:
|
|||
in: header
|
||||
name: Authorization
|
||||
type: apiKey
|
||||
QuerystringAuthentication:
|
||||
description: |
|
||||
Use the query string authentication scheme with InfluxDB v1-compatible API operations.
|
||||
Pass your InfluxDB username and API token as query parameters using `u` for username and `p` for password (API token).
|
||||
|
||||
### Syntax
|
||||
|
||||
`?u=USERNAME&p=INFLUX_API_TOKEN`
|
||||
|
||||
### Example
|
||||
|
||||
```sh
|
||||
curl --get "INFLUX_URL/query" \
|
||||
--data-urlencode "u=USERNAME" \
|
||||
--data-urlencode "p=INFLUX_API_TOKEN" \
|
||||
--data-urlencode "q=SHOW DATABASES"
|
||||
```
|
||||
|
||||
Replace the following:
|
||||
|
||||
- *`INFLUX_URL`*: your InfluxDB URL
|
||||
- *`USERNAME`*: your InfluxDB username
|
||||
- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/v2/reference/glossary/#token)
|
||||
|
||||
> [!Warning]
|
||||
> Query string authentication exposes your credentials in the URL and server logs.
|
||||
> Use [Token authentication](#section/Authentication/TokenAuthentication) for production environments.
|
||||
in: query
|
||||
name: u
|
||||
type: apiKey
|
||||
x-tagGroups:
|
||||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
|
|
@ -20204,7 +20250,7 @@ x-tagGroups:
|
|||
- NotificationRules
|
||||
- Organizations
|
||||
- Ping
|
||||
- Query
|
||||
- Query data
|
||||
- Query data (v1-compatible)
|
||||
- Ready
|
||||
- RemoteConnections
|
||||
|
|
@ -20226,5 +20272,5 @@ x-tagGroups:
|
|||
- Users
|
||||
- Variables
|
||||
- Views
|
||||
- Write
|
||||
- Write data
|
||||
- Write data (v1-compatible)
|
||||
|
|
|
|||
|
|
@ -6,13 +6,11 @@ extends:
|
|||
x-influxdata-product-name: InfluxDB 3 Cloud Dedicated
|
||||
|
||||
apis:
|
||||
management@0:
|
||||
root: management/openapi.yml
|
||||
v2@2:
|
||||
root: v2/ref.yml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb3/cloud-dedicated/api/
|
||||
v1-compatibility@2:
|
||||
root: v1-compatibility/swaggerV1Compat.yml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb3/cloud-dedicated/api/v1/
|
||||
- /influxdb3/cloud-dedicated/api/v2/
|
||||
- /influxdb3/cloud-dedicated/api/v1-compatibility
|
||||
- /influxdb3/cloud-dedicated/api/v2-compatibility
|
||||
|
|
|
|||
|
|
@ -1,6 +0,0 @@
|
|||
- name: Using the Management API
|
||||
tags:
|
||||
- Authentication
|
||||
- Quickstart
|
||||
- name: All endpoints
|
||||
tags: []
|
||||
|
|
@ -28,269 +28,47 @@ security:
|
|||
- bearerAuthManagementToken: []
|
||||
bearerAuthJwt: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
x-traitTag: true
|
||||
description: |
|
||||
With InfluxDB 3 Cloud Dedicated, the InfluxDB Management API endpoints require the following credentials:
|
||||
|
||||
- `ACCOUNT_ID`: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the cluster belongs to. To view account ID and cluster ID, [list cluster details](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json).
|
||||
- `CLUSTER_ID`: The ID of the [cluster](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that you want to manage. To view account ID and cluster ID, [list cluster details](/influxdb3/cloud-dedicated/admin/clusters/list/#detailed-output-in-json).
|
||||
- `Authorization MANAGEMENT_TOKEN`: the `Authorization` HTTP header with a [management token](/influxdb3/cloud-dedicated/admin/tokens/management/).
|
||||
|
||||
See how to [create a management token](/influxdb3/cloud-dedicated/admin/tokens/management/).
|
||||
|
||||
By default, management tokens in InfluxDB 3 are short-lived tokens issued by an OAuth2 identity provider that grant a specific user administrative access to your InfluxDB cluster. However, for automation purposes, you can manually create management tokens that authenticate directly with your InfluxDB cluster and do not require human interaction with your identity provider.
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
- name: Database tokens
|
||||
description: Manage database read/write tokens for a cluster
|
||||
- name: Databases
|
||||
description: Manage databases for a cluster
|
||||
- name: Quickstart
|
||||
- name: Quick start
|
||||
x-traitTag: true
|
||||
description: |
|
||||
The following example script shows how to use `curl` to make database and token management requests:
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
```shell
|
||||
#!/bin/bash
|
||||
1. Create a management token using `influxctl token create`.
|
||||
|
||||
# Usage:
|
||||
# Note the leading space in the command below to keep secrets out of the shell history
|
||||
#
|
||||
# ```
|
||||
# MANAGEMENT_TOKEN=<MANAGEMENT_TOKEN> ACCOUNT_ID=<ACCOUNT_ID> CLUSTER_ID=<CLUSTER_ID> ./scripts/test_http_api_v0_endpoints.sh
|
||||
# ```
|
||||
2. Create a database using the Management API.
|
||||
|
||||
# Env var validation
|
||||
if [ -z "${MANAGEMENT_TOKEN}" ]; then
|
||||
echo "
|
||||
[Error]: ❌
|
||||
\$MANAGEMENT_TOKEN env var is required.
|
||||
"
|
||||
exit 1
|
||||
fi
|
||||
```bash
|
||||
curl -X POST "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/databases" \
|
||||
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{"name": "sensors"}'
|
||||
```
|
||||
|
||||
if [ -z "${ACCOUNT_ID}" ]; then
|
||||
echo "
|
||||
[Error]: ❌
|
||||
\$ACCOUNT_ID env var is required.
|
||||
"
|
||||
exit 1
|
||||
fi
|
||||
3. Create a database token for read/write access.
|
||||
|
||||
if [ -z "${CLUSTER_ID}" ]; then
|
||||
echo "
|
||||
[Error]: ❌
|
||||
\$CLUSTER_ID env var is required.
|
||||
"
|
||||
exit 1
|
||||
fi
|
||||
```bash
|
||||
curl -X POST "https://console.influxdata.com/api/v0/accounts/ACCOUNT_ID/clusters/CLUSTER_ID/tokens" \
|
||||
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{"description": "my token", "permissions": [{"action": "write", "resource": "sensors"}]}'
|
||||
```
|
||||
|
||||
HOST="https://console.influxdata.com"
|
||||
4. Write data to InfluxDB Cloud Dedicated.
|
||||
|
||||
# Database request functions
|
||||
list_databases () {
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/databases" \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
```bash
|
||||
curl -X POST "https://CLUSTER_HOST/api/v2/write?bucket=sensors&precision=ns" \
|
||||
--header "Authorization: Token DATABASE_TOKEN" \
|
||||
--data-raw "home,room=Kitchen temp=72.0"
|
||||
```
|
||||
|
||||
create_database () {
|
||||
local databaseName=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/databases" \
|
||||
--header "Accept: application/json" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
--data '{
|
||||
"name": "'$databaseName'",
|
||||
"maxTables": 75,
|
||||
"maxColumnsPerTable": 90,
|
||||
"retentionPeriod": 600000000000,
|
||||
"partitionTemplate": [
|
||||
{
|
||||
"type": "tag",
|
||||
"value": "abc"
|
||||
},
|
||||
{
|
||||
"type": "bucket",
|
||||
"value": {
|
||||
"tagName": "def",
|
||||
"numberOfBuckets": 5
|
||||
}
|
||||
}
|
||||
]
|
||||
}' \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
5. Query data using SQL or InfluxQL with a Flight client or the HTTP API.
|
||||
|
||||
update_database () {
|
||||
local databaseName=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/databases/$databaseName" \
|
||||
--request PATCH \
|
||||
--header "Accept: application/json" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
--data '{
|
||||
"maxTables": 150,
|
||||
"maxColumnsPerTable": 180,
|
||||
"retentionPeriod": 1200000000000
|
||||
}' \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
delete_database () {
|
||||
local databaseName=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/databases/$databaseName" \
|
||||
--request DELETE \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
# Token request functions
|
||||
list_tokens () {
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/tokens" \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
create_token () {
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/tokens" \
|
||||
--header "Accept: application/json" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
--data '{
|
||||
"description": "my test token",
|
||||
"permissions": [
|
||||
{
|
||||
"action": "write",
|
||||
"resource": "database_one"
|
||||
},
|
||||
{
|
||||
"action": "read",
|
||||
"resource": "database_two"
|
||||
}
|
||||
]
|
||||
}' \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
get_token () {
|
||||
local token_id=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/tokens/$tokenId" \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
update_token () {
|
||||
local token_id=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/tokens/$tokenId" \
|
||||
--request PATCH \
|
||||
--header "Accept: application/json" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
--data '{
|
||||
"description": "my updated test token",
|
||||
"permissions": [
|
||||
{
|
||||
"action": "database_one",
|
||||
"resource": "read"
|
||||
}
|
||||
]
|
||||
}' \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
delete_token () {
|
||||
local token_id=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/tokens/$tokenId" \
|
||||
--request DELETE \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
|
||||
# Test database endpoints
|
||||
databaseName="test_database_$RANDOM"
|
||||
|
||||
printf "\n🏗️ Creating database... 🏗️\n\n"
|
||||
response="$(create_database $databaseName)"
|
||||
echo $response | jq
|
||||
printf "\n🏗️ Creating database successful 🏗️\n\n"
|
||||
|
||||
printf "\n⬆️ Updating database... ⬆️\n\n"
|
||||
response="$(update_database $databaseName)"
|
||||
echo $response | jq
|
||||
printf "\n⬆️ Updating database successful ⬆️\n\n"
|
||||
|
||||
printf "\n⬇️ Listing databases... ⬇️\n\n"
|
||||
response="$(list_databases)"
|
||||
echo $response | jq
|
||||
printf "\n⬇️ Listing databases successful ⬇️\n\n"
|
||||
|
||||
printf "\n🗑️ Deleting database... 🗑️\n\n"
|
||||
response="$(delete_database $databaseName)"
|
||||
echo $response | jq
|
||||
printf "\n🗑️ Deleting database successful 🗑️\n\n"
|
||||
|
||||
|
||||
# Test token endpoints
|
||||
printf "\n🏗️ Creating token... 🏗️\n\n"
|
||||
response="$(create_token)"
|
||||
echo $response | jq
|
||||
tokenId=$(echo $response | jq '.id')
|
||||
printf "\n🏗️ Creating token successful 🏗️\n\n"
|
||||
|
||||
printf "\n⬇️ Getting token... ⬇️\n\n"
|
||||
response="$(get_token $tokenId)"
|
||||
echo $response | jq
|
||||
printf "\n⬇️ Getting token successful ⬇️\n\n"
|
||||
|
||||
printf "\n⬆️ Updating token... ⬆️\n\n"
|
||||
response="$(update_token $tokenId)"
|
||||
echo $response | jq
|
||||
printf "\n⬆️ Updating token successful ⬆️\n\n"
|
||||
|
||||
printf "\n📋 Listing tokens... 📋\n\n"
|
||||
response="$(list_tokens)"
|
||||
echo $response | jq
|
||||
printf "\n📋 Listing tokens successful 📋\n\n"
|
||||
|
||||
printf "\n🗑️ Deleting token... 🗑️\n\n"
|
||||
response="$(delete_token $tokenId)"
|
||||
echo $response | jq
|
||||
printf "\n🗑️ Deleting token successful 🗑️\n\n"
|
||||
```
|
||||
For more information, see the
|
||||
[Get started](/influxdb3/cloud-dedicated/get-started/) guide.
|
||||
- name: Tables
|
||||
description: Manage tables in a database
|
||||
paths:
|
||||
|
|
@ -2425,8 +2203,7 @@ components:
|
|||
x-tagGroups:
|
||||
- name: Using the Management API
|
||||
tags:
|
||||
- Authentication
|
||||
- Quickstart
|
||||
- Quick start
|
||||
- name: All endpoints
|
||||
tags:
|
||||
- Database tokens
|
||||
|
|
|
|||
|
|
@ -1,13 +0,0 @@
|
|||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
- Quick start
|
||||
- API compatibility
|
||||
- Authentication
|
||||
- Headers
|
||||
- Pagination
|
||||
- Response codes
|
||||
- name: All endpoints
|
||||
tags:
|
||||
- Ping
|
||||
- Query
|
||||
- Write
|
||||
|
|
@ -32,49 +32,68 @@ security:
|
|||
- QuerystringAuthentication: []
|
||||
tags:
|
||||
- description: |
|
||||
Use InfluxDB v1 and v2 compatible endpoints to write and query data.
|
||||
|
||||
### Write data
|
||||
|
||||
InfluxDB 3 Cloud Dedicated provides the following HTTP API endpoints for writing data:
|
||||
|
||||
- **Recommended**: [`/api/v2/write` endpoint](#operation/PostWrite) for new write workloads or for bringing existing InfluxDB v2 write workloads to InfluxDB 3.
|
||||
- [`/write` endpoint](#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to InfluxDB 3.
|
||||
- `/api/v2/write` endpoint (recommended) for new write workloads or for
|
||||
bringing existing InfluxDB v2 write workloads to InfluxDB Cloud Dedicated.
|
||||
- `/write` endpoint for bringing existing InfluxDB v1 write workloads to
|
||||
InfluxDB Cloud Dedicated.
|
||||
|
||||
Both endpoints accept the same line protocol format and process data in the same way.
|
||||
Both endpoints accept line protocol format and process data the same way.
|
||||
|
||||
### Query data
|
||||
|
||||
InfluxDB 3 Cloud Dedicated provides the following protocols for executing a query:
|
||||
|
||||
- **Recommended**: _Flight+gRPC_ request that contains an SQL or InfluxQL query. See how to [get started querying InfluxDB using Flight and SQL](/influxdb3/cloud-dedicated/get-started/query/).
|
||||
- HTTP API [`/query` request](#operation/GetLegacyQuery) that contains an InfluxQL query.
|
||||
Use this protocol when bringing existing InfluxDB v1 query workloads to InfluxDB 3.
|
||||
- Flight+gRPC request (recommended) that contains an SQL or InfluxQL query.
|
||||
- HTTP API `/query` request that contains an InfluxQL query.
|
||||
Use this protocol for existing InfluxDB v1 query workloads.
|
||||
|
||||
### InfluxDB v2 compatibility
|
||||
|
||||
The HTTP API [`/api/v2/write` endpoint](#operation/PostWrite) works with the [`Bearer`](#section/Authentication/BearerAuthentication) and [`Token`](#section/Authentication/TokenAuthentication) authentication schemes and existing InfluxDB 2.x tools and code for [writing data](/influxdb3/cloud-dedicated/write-data/).
|
||||
|
||||
See how to [use the InfluxDB v2 HTTP API with InfluxDB 3 Cloud Dedicated](/influxdb3/cloud-dedicated/guides/api-compatibility/v2/).
|
||||
The `/api/v2/write` endpoint works with Bearer and Token authentication
|
||||
and existing InfluxDB 2.x tools and code.
|
||||
|
||||
### InfluxDB v1 compatibility
|
||||
|
||||
The HTTP API [`/write` endpoint](#operation/PostLegacyWrite) and [`/query` endpoint](#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
|
||||
|
||||
See how to [use the InfluxDB v1 HTTP API with InfluxDB 3 Cloud Dedicated](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/).
|
||||
The `/write` and `/query` endpoints work with InfluxDB 1.x username/password
|
||||
authentication and existing InfluxDB 1.x tools and code.
|
||||
name: API compatibility
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API:
|
||||
Authenticate API requests using tokens, basic auth, or query strings.
|
||||
|
||||
| Authentication scheme | Works with |
|
||||
|:-------------------|:-----------|
|
||||
| [Bearer authentication](#section/Authentication/BearerAuthentication) | All endpoints |
|
||||
| [Token authentication](#section/Authentication/TokenAuthentication) | v1, v2 endpoints |
|
||||
| [Basic authentication](#section/Authentication/BasicAuthentication) | v1 endpoints |
|
||||
| [Querystring authentication](#section/Authentication/QuerystringAuthentication) | v1 endpoints |
|
||||
## Token types
|
||||
|
||||
InfluxDB 3 Cloud Dedicated uses two types of tokens for API authentication:
|
||||
|
||||
| Token type | Used for | How to create |
|
||||
|:-----------|:---------|:--------------|
|
||||
| **Management token** | Management operations (`/api/v0/*`) - manage databases, tables, and database tokens | [`influxctl management create`](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/create/) |
|
||||
| **Database token** | Data API (`/api/v2/write`, `/query`, etc.) - write and query data | [Database tokens API](/influxdb3/cloud-dedicated/api/database-tokens/) or [`influxctl token create`](/influxdb3/cloud-dedicated/reference/cli/influxctl/token/create/) |
|
||||
|
||||
## Authentication schemes
|
||||
|
||||
Choose an authentication scheme based on the endpoint and your workflow:
|
||||
|
||||
| Scheme | Token type | Endpoints | Header format |
|
||||
|:-------|:-----------|:----------|:--------------|
|
||||
| [Bearer](#section/Authentication/BearerAuthentication) | Database | All data endpoints | `Authorization: Bearer DATABASE_TOKEN` |
|
||||
| [Token](#section/Authentication/TokenAuthentication) | Database | v1, v2 endpoints | `Authorization: Token DATABASE_TOKEN` |
|
||||
| [Basic](#section/Authentication/BasicAuthentication) | Database | v1 endpoints | `Authorization: Basic base64(username:DATABASE_TOKEN)` |
|
||||
| [Query string](#section/Authentication/QuerystringAuthentication) | Database | v1 endpoints | `?u=username&p=DATABASE_TOKEN` |
|
||||
|
||||
Management operations (`/api/v0/*`) require a management token in the `Authorization: Bearer` header.
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
name: Authentication
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Parameters for specifying resources in API requests.
|
||||
|
||||
To specify resources, some InfluxDB API endpoints require parameters or
|
||||
properties in the request--for example,
|
||||
writing to a `database` resource.
|
||||
|
|
@ -86,9 +105,6 @@ tags:
|
|||
| `database`, `db` | string | The database name |
|
||||
name: Common parameters
|
||||
x-traitTag: true
|
||||
- name: Data I/O endpoints
|
||||
description: |
|
||||
Write and query data stored in InfluxDB.
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
|
|
@ -98,7 +114,7 @@ tags:
|
|||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `Authorization` | string | The authorization scheme and credential. |
|
||||
| `Authorization` | string | The [authorization scheme and credential](/influxdb/version/api/authentication/). |
|
||||
| `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. |
|
||||
| `Content-Type` | string | The format of the data in the request body. |
|
||||
name: Headers
|
||||
|
|
@ -107,22 +123,48 @@ tags:
|
|||
- description: |
|
||||
Query data stored in a database.
|
||||
|
||||
- HTTP clients can query the v1 [`/query` endpoint](#operation/GetLegacyQuery)
|
||||
- HTTP clients can query the v1 [`/query` endpoint](/influxdb3/cloud-dedicated/api/query-data/)
|
||||
using **InfluxQL** and retrieve data in **CSV** or **JSON** format.
|
||||
- The `/api/v2/query` endpoint can't query InfluxDB 3 Cloud Dedicated.
|
||||
- _Flight + gRPC_ clients can query using **SQL** or **InfluxQL** and retrieve data in **Arrow** format.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Get started querying InfluxDB](/influxdb3/cloud-dedicated/get-started/query/)
|
||||
- [Execute queries](/influxdb3/cloud-dedicated/query-data/execute-queries/)
|
||||
name: Query
|
||||
name: Query data
|
||||
x-influxdatadocs-related:
|
||||
- /influxdb3/cloud-dedicated/get-started/query/
|
||||
- /influxdb3/cloud-dedicated/query-data/execute-queries/
|
||||
- description: |
|
||||
See the [**Get Started**](/influxdb3/cloud-dedicated/get-started/) tutorial
|
||||
to get up and running authenticating with tokens, writing to databases, and querying data.
|
||||
Get started with the InfluxDB 3 Cloud Dedicated API:
|
||||
|
||||
[**InfluxDB API client libraries and Flight clients**](/influxdb3/cloud-dedicated/reference/client-libraries/)
|
||||
are available to integrate InfluxDB APIs with your application.
|
||||
1. **Create a management token** using [`influxctl management create`](/influxdb3/cloud-dedicated/reference/cli/influxctl/management/create/).
|
||||
|
||||
2. **Create a database** using the [Databases API](/influxdb3/cloud-dedicated/api/databases/).
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cluster-id.a.influxdb.io/api/v0/databases" \
|
||||
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{"name": "sensors"}'
|
||||
```
|
||||
|
||||
3. **Create a database token** for read/write access.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cluster-id.a.influxdb.io/api/v0/tokens" \
|
||||
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{"description": "my token", "permissions": [{"action": "write", "resource": "sensors"}]}'
|
||||
```
|
||||
|
||||
4. **Write data** to InfluxDB 3 Cloud Dedicated.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cluster-id.a.influxdb.io/api/v2/write?bucket=sensors&precision=ns" \
|
||||
--header "Authorization: Token DATABASE_TOKEN" \
|
||||
--data-raw "home,room=Kitchen temp=72.0"
|
||||
```
|
||||
|
||||
5. **Query data** using SQL or InfluxQL with a [Flight client](/influxdb3/cloud-dedicated/query-data/execute-queries/flight-sql/) or the HTTP [`/query` endpoint](/influxdb3/cloud-dedicated/api/query-data/).
|
||||
|
||||
For more information, see the [Get started](/influxdb3/cloud-dedicated/get-started/) guide.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
|
|
@ -151,7 +193,7 @@ tags:
|
|||
- name: Usage
|
||||
- description: |
|
||||
Write time series data to [databases](/influxdb3/cloud-dedicated/admin/databases/) using InfluxDB v1 or v2 endpoints.
|
||||
name: Write
|
||||
name: Write data
|
||||
paths:
|
||||
/ping:
|
||||
get:
|
||||
|
|
@ -254,18 +296,16 @@ paths:
|
|||
|
||||
#### Write endpoints
|
||||
|
||||
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB 3 Cloud Dedicated.
|
||||
The [`/write`](/influxdb3/cloud-dedicated/api/write-data/) and [`/api/v2/write`](/influxdb3/cloud-dedicated/api/write-data/) endpoints are functionally equivalent for writing data to InfluxDB Cloud Dedicated.
|
||||
|
||||
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/).
|
||||
- Use the [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v2/).
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Get started writing data](/influxdb3/cloud-dedicated/get-started/write/)
|
||||
- [Write data](/influxdb3/cloud-dedicated/write-data/)
|
||||
- [Best practices for writing data](/influxdb3/cloud-dedicated/write-data/best-practices/)
|
||||
- [Troubleshoot issues writing data](/influxdb3/cloud-dedicated/write-data/troubleshoot/)
|
||||
- Use the [`/write` endpoint](/influxdb3/cloud-dedicated/api/write-data/) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/).
|
||||
- Use the [`/api/v2/write` endpoint](/influxdb3/cloud-dedicated/api/write-data/) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v2/).
|
||||
operationId: PostWrite
|
||||
x-influxdatadocs-related:
|
||||
- /influxdb3/cloud-dedicated/get-started/write/
|
||||
- /influxdb3/cloud-dedicated/write-data/
|
||||
- /influxdb3/cloud-dedicated/write-data/best-practices/
|
||||
- /influxdb3/cloud-dedicated/write-data/troubleshoot/
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- description: |
|
||||
|
|
@ -313,10 +353,6 @@ paths:
|
|||
|
||||
- Returns only `application/json` for format and limit errors.
|
||||
- Returns only `text/html` for some quota limit errors.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Troubleshoot issues writing data](/influxdb3/cloud-dedicated/write-data/troubleshoot/)
|
||||
in: header
|
||||
name: Accept
|
||||
schema:
|
||||
|
|
@ -378,10 +414,6 @@ paths:
|
|||
1. Use [gzip](https://www.gzip.org/) to compress the line protocol data.
|
||||
2. In your request, send the compressed data and the
|
||||
`Content-Encoding: gzip` header.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Best practices for optimizing writes](/influxdb3/cloud-dedicated/write-data/best-practices/optimize-writes/)
|
||||
required: true
|
||||
responses:
|
||||
'201':
|
||||
|
|
@ -427,10 +459,9 @@ paths:
|
|||
|
||||
default:
|
||||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Write data
|
||||
summary: Write data using the InfluxDB v2 HTTP API
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Write
|
||||
- Write data
|
||||
/query:
|
||||
get:
|
||||
description: Queries InfluxDB using InfluxQL with InfluxDB v1 request and response formats.
|
||||
|
|
@ -567,8 +598,7 @@ paths:
|
|||
description: Error processing query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
tags:
|
||||
- Query
|
||||
- Data I/O endpoints
|
||||
- Query data
|
||||
/write:
|
||||
post:
|
||||
operationId: PostLegacyWrite
|
||||
|
|
@ -596,17 +626,15 @@ paths:
|
|||
|
||||
#### Write endpoints
|
||||
|
||||
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB 3 Cloud Dedicated.
|
||||
The [`/write`](/influxdb3/cloud-dedicated/api/write-data/) and [`/api/v2/write`](/influxdb3/cloud-dedicated/api/write-data/) endpoints are functionally equivalent for writing data to InfluxDB Cloud Dedicated.
|
||||
|
||||
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/).
|
||||
- Use the [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v2/).
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Get started writing data](/influxdb3/cloud-dedicated/get-started/write/)
|
||||
- [Write data](/influxdb3/cloud-dedicated/write-data/)
|
||||
- [Best practices for writing data](/influxdb3/cloud-dedicated/write-data/best-practices/)
|
||||
- [Troubleshoot issues writing data](/influxdb3/cloud-dedicated/write-data/troubleshoot/)
|
||||
- Use the [`/write` endpoint](/influxdb3/cloud-dedicated/api/write-data/) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/).
|
||||
- Use the [`/api/v2/write` endpoint](/influxdb3/cloud-dedicated/api/write-data/) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v2/).
|
||||
x-influxdatadocs-related:
|
||||
- /influxdb3/cloud-dedicated/get-started/write/
|
||||
- /influxdb3/cloud-dedicated/write-data/
|
||||
- /influxdb3/cloud-dedicated/write-data/best-practices/
|
||||
- /influxdb3/cloud-dedicated/write-data/troubleshoot/
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- description: The InfluxDB 1.x username to authenticate the request.
|
||||
|
|
@ -715,8 +743,7 @@ paths:
|
|||
description: Internal server error
|
||||
summary: Write data using the InfluxDB v1 HTTP API
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Write
|
||||
- Write data
|
||||
components:
|
||||
parameters:
|
||||
TraceSpan:
|
||||
|
|
@ -1045,9 +1072,7 @@ components:
|
|||
Annotation rows to include in the results.
|
||||
An _annotation_ is metadata associated with an object (column) in the data model.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- See [Annotated CSV annotations](/influxdb3/cloud-dedicated/reference/syntax/annotated-csv/#annotations) for examples and more information.
|
||||
See [Annotated CSV annotations](/influxdb3/cloud-dedicated/reference/syntax/annotated-csv/#annotations) for examples and more information.
|
||||
|
||||
For more information about **annotations** in tabular data,
|
||||
see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns).
|
||||
|
|
@ -1811,9 +1836,7 @@ components:
|
|||
|
||||
- Doesn't use `shardGroupDurationsSeconds`.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- InfluxDB [shards and shard groups](/influxdb3/cloud-dedicated/reference/internals/shards/)
|
||||
For more information, see [shards and shard groups](/influxdb3/cloud-dedicated/reference/internals/shards/).
|
||||
format: int64
|
||||
type: integer
|
||||
type:
|
||||
|
|
@ -1958,7 +1981,7 @@ components:
|
|||
description: |
|
||||
Use the `Authorization` header with the `Basic` scheme to authenticate v1 API requests.
|
||||
|
||||
Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints in InfluxDB 3.
|
||||
Works with v1 compatibility [`/write`](/influxdb3/cloud-dedicated/api/write-data/) and [`/query`](/influxdb3/cloud-dedicated/api/query-data/) endpoints in InfluxDB 3.
|
||||
|
||||
When authenticating requests, InfluxDB 3 checks that the `password` part of the decoded credential is an authorized token
|
||||
and ignores the `username` part of the decoded credential.
|
||||
|
|
@ -1977,10 +2000,8 @@ components:
|
|||
- **`DATABASE_NAME`**: your InfluxDB 3 Cloud Dedicated database
|
||||
- **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/)
|
||||
- [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/)
|
||||
For more information, see [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/)
|
||||
and [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/).
|
||||
QuerystringAuthentication:
|
||||
type: apiKey
|
||||
in: query
|
||||
|
|
@ -1988,7 +2009,7 @@ components:
|
|||
description: |
|
||||
Use InfluxDB 1.x API parameters to provide credentials through the query string for v1 API requests.
|
||||
|
||||
Querystring authentication works with v1-compatible [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints.
|
||||
Querystring authentication works with v1-compatible [`/write`](/influxdb3/cloud-dedicated/api/write-data/) and [`/query`](/influxdb3/cloud-dedicated/api/query-data/) endpoints.
|
||||
|
||||
When authenticating requests, InfluxDB 3 checks that the `p` (_password_) query parameter is an authorized token
|
||||
and ignores the `u` (_username_) query parameter.
|
||||
|
|
@ -2033,10 +2054,8 @@ components:
|
|||
- **`DATABASE_NAME`**: the database to query
|
||||
- **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/)
|
||||
- [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/)
|
||||
For more information, see [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/)
|
||||
and [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/).
|
||||
BearerAuthentication:
|
||||
type: http
|
||||
scheme: bearer
|
||||
|
|
@ -2044,7 +2063,7 @@ components:
|
|||
description: |
|
||||
|
||||
Use the OAuth Bearer authentication
|
||||
scheme to provide an authorization token to InfluxDB 3.
|
||||
scheme to provide an authorization token to InfluxDB Cloud Dedicated.
|
||||
|
||||
Bearer authentication works with all endpoints.
|
||||
|
||||
|
|
@ -2066,9 +2085,9 @@ components:
|
|||
```
|
||||
TokenAuthentication:
|
||||
description: |
|
||||
Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB 3.
|
||||
Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB Cloud Dedicated.
|
||||
|
||||
The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB 3.
|
||||
The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB Cloud Dedicated.
|
||||
|
||||
In your API requests, send an `Authorization` header.
|
||||
For the header value, provide the word `Token` followed by a space and a database token.
|
||||
|
|
@ -2093,9 +2112,7 @@ components:
|
|||
--data-binary 'home,room=kitchen temp=72 1463683075'
|
||||
```
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/)
|
||||
For more information, see [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/).
|
||||
in: header
|
||||
name: Authorization
|
||||
type: apiKey
|
||||
|
|
@ -2111,5 +2128,5 @@ x-tagGroups:
|
|||
- name: All endpoints
|
||||
tags:
|
||||
- Ping
|
||||
- Query
|
||||
- Write
|
||||
- Query data
|
||||
- Write data
|
||||
|
|
|
|||
|
|
@ -1,28 +0,0 @@
|
|||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
- Quick start
|
||||
- Authentication
|
||||
- Supported operations
|
||||
- Headers
|
||||
- Pagination
|
||||
- Response codes
|
||||
- name: All endpoints
|
||||
tags:
|
||||
- Authorizations (API tokens)
|
||||
- Bucket Schemas
|
||||
- Buckets
|
||||
- Delete
|
||||
- DBRPs
|
||||
- Invokable Scripts
|
||||
- Limits
|
||||
- Organizations
|
||||
- Query
|
||||
- Resources
|
||||
- Routes
|
||||
- Secrets
|
||||
- Tasks
|
||||
- Telegrafs
|
||||
- Templates
|
||||
- Usage
|
||||
- Variables
|
||||
- Write
|
||||
|
|
@ -29,38 +29,41 @@ security:
|
|||
- TokenAuthentication: []
|
||||
tags:
|
||||
- description: |
|
||||
Use InfluxDB v1 and v2 compatible endpoints to write and query data.
|
||||
|
||||
### Write data
|
||||
|
||||
InfluxDB 3 Cloud Serverless provides the following HTTP API endpoints for writing data:
|
||||
|
||||
- **Recommended**: [`/api/v2/write` endpoint](#operation/PostWrite)
|
||||
for new write workloads or for bringing existing InfluxDB v2 write workloads to InfluxDB 3.
|
||||
- [`/write` endpoint](#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to InfluxDB 3.
|
||||
- `/api/v2/write` endpoint (recommended) for new write workloads or for
|
||||
bringing existing InfluxDB v2 write workloads to InfluxDB Cloud Serverless.
|
||||
- `/write` endpoint for bringing existing InfluxDB v1 write workloads to
|
||||
InfluxDB Cloud Serverless.
|
||||
|
||||
Both endpoints accept the same line protocol format and process data in the same way.
|
||||
Both endpoints accept line protocol format and process data the same way.
|
||||
|
||||
### Query data
|
||||
|
||||
InfluxDB 3 Cloud Serverless provides the following protocols for executing a query:
|
||||
|
||||
- **Recommended**: _Flight+gRPC_ request that contains an SQL or InfluxQL query. See how to [get started querying InfluxDB using Flight and SQL](/influxdb3/cloud-serverless/get-started/query/).
|
||||
- HTTP API [`/query` request](/influxdb3/cloud-serverless/api/#operation/GetLegacyQuery) that contains an InfluxQL query.
|
||||
Use this protocol when bringing existing InfluxDB v1 query workloads to InfluxDB 3.
|
||||
- Flight+gRPC request (recommended) that contains an SQL or InfluxQL query.
|
||||
- HTTP API `/query` request that contains an InfluxQL query.
|
||||
Use this protocol for existing InfluxDB v1 query workloads.
|
||||
|
||||
### InfluxDB v2 compatibility
|
||||
|
||||
The HTTP API [`/api/v2/write` endpoint](#operation/PostWrite) works with the [`Token` authentication scheme](#section/Authentication/TokenAuthentication) and existing InfluxDB 2.x tools and code for [writing data](/influxdb3/cloud-serverless/write-data/).
|
||||
|
||||
See how to [use the InfluxDB v2 HTTP API with InfluxDB 3 Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v2/).
|
||||
The `/api/v2/write` endpoint works with Token authentication and existing
|
||||
InfluxDB 2.x tools and code.
|
||||
|
||||
### InfluxDB v1 compatibility
|
||||
|
||||
The HTTP API [`/write` endpoint](#operation/PostLegacyWrite) and [`/query` endpoint](#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
|
||||
|
||||
See how to [use the InfluxDB v1 HTTP API with InfluxDB 3 Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/).
|
||||
The `/write` and `/query` endpoints work with InfluxDB 1.x username/password
|
||||
authentication and existing InfluxDB 1.x tools and code.
|
||||
name: API compatibility
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Authenticate API requests using tokens, basic auth, or query strings.
|
||||
|
||||
Use one of the following schemes to authenticate to the InfluxDB API:
|
||||
|
||||
- [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
|
|
@ -116,6 +119,8 @@ tags:
|
|||
- name: Cells
|
||||
- name: Checks
|
||||
- description: |
|
||||
Parameters for specifying resources in API requests.
|
||||
|
||||
To specify resources, some InfluxDB API endpoints require parameters or
|
||||
properties in the request--for example,
|
||||
writing to a `bucket` resource in an `org` (_organization_ resource).
|
||||
|
|
@ -132,7 +137,6 @@ tags:
|
|||
x-traitTag: true
|
||||
- name: Config
|
||||
- name: Dashboards
|
||||
- name: Data I/O endpoints
|
||||
- description: |
|
||||
The InfluxDB 1.x data model includes [databases](/influxdb3/cloud-serverless/reference/glossary/#database)
|
||||
and [retention policies](/influxdb3/cloud-serverless/reference/glossary/#retention-policy-rp).
|
||||
|
|
@ -159,7 +163,7 @@ tags:
|
|||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `Authorization` | string | The authorization scheme and credential. |
|
||||
| `Authorization` | string | The [authorization scheme and credential](/influxdb/version/api/authentication/). |
|
||||
| `Content-Length` | integer | The size of the entity-body, in bytes. |
|
||||
| `Content-Type` | string | The format of the data in the request body. |
|
||||
name: Headers
|
||||
|
|
@ -245,13 +249,38 @@ tags:
|
|||
|
||||
- [Get started querying InfluxDB](/influxdb3/cloud-serverless/get-started/query/)
|
||||
- [Execute queries](/influxdb3/cloud-serverless/query-data/execute-queries/)
|
||||
name: Query
|
||||
name: Query data
|
||||
- description: |
|
||||
See the [**Get started**](/influxdb3/cloud-serverless/get-started/) tutorial
|
||||
to get up and running authenticating with tokens, writing to buckets, and querying data.
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
[**InfluxDB API client libraries and Flight clients**](/influxdb3/cloud-serverless/reference/client-libraries/)
|
||||
are available to integrate InfluxDB with your application.
|
||||
1. Create a database token to authorize API requests in the InfluxDB Cloud
|
||||
Serverless UI.
|
||||
|
||||
2. Write data to InfluxDB Cloud Serverless.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cloud2.influxdata.com/api/v2/write?bucket=DATABASE_NAME&precision=ns" \
|
||||
--header "Authorization: Token DATABASE_TOKEN" \
|
||||
--header "Content-Type: text/plain; charset=utf-8" \
|
||||
--data-raw "home,room=Kitchen temp=72.0
|
||||
home,room=Living\ room temp=71.5"
|
||||
```
|
||||
|
||||
If all data is written, the response is `204 No Content`.
|
||||
|
||||
3. Query data from InfluxDB Cloud Serverless using SQL or InfluxQL.
|
||||
For best performance, use a Flight client to query data.
|
||||
The HTTP API `/query` endpoint supports InfluxQL queries.
|
||||
|
||||
```bash
|
||||
curl -G "https://cloud2.influxdata.com/query" \
|
||||
--header "Authorization: Token DATABASE_TOKEN" \
|
||||
--data-urlencode "db=DATABASE_NAME" \
|
||||
--data-urlencode "q=SELECT * FROM home WHERE time > now() - 1h"
|
||||
```
|
||||
|
||||
For more information about using InfluxDB Cloud Serverless, see the
|
||||
[Get started](/influxdb3/cloud-serverless/get-started/) guide.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- name: Resources
|
||||
|
|
@ -357,7 +386,7 @@ tags:
|
|||
- name: Views
|
||||
- description: |
|
||||
Write time series data to [buckets](/influxdb3/cloud-serverless/reference/glossary/#bucket) using InfluxDB v1 or v2 endpoints.
|
||||
name: Write
|
||||
name: Write data
|
||||
paths:
|
||||
/api/v2:
|
||||
get:
|
||||
|
|
@ -3885,7 +3914,7 @@ paths:
|
|||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Query data
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
/api/v2/query/analyze:
|
||||
post:
|
||||
deprecated: true
|
||||
|
|
@ -3989,7 +4018,7 @@ paths:
|
|||
type: string
|
||||
summary: Analyze a Flux query
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
/api/v2/query/ast:
|
||||
post:
|
||||
deprecated: true
|
||||
|
|
@ -4052,7 +4081,7 @@ paths:
|
|||
description: Internal server error.
|
||||
summary: Generate a query Abstract Syntax Tree (AST)
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
/api/v2/query/suggestions:
|
||||
get:
|
||||
deprecated: true
|
||||
|
|
@ -4095,7 +4124,7 @@ paths:
|
|||
description: Internal server error.
|
||||
summary: List Flux query suggestions
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
x-codeSamples:
|
||||
- label: cURL
|
||||
lang: Shell
|
||||
|
|
@ -4142,7 +4171,7 @@ paths:
|
|||
The value passed for _`name`_ may have been misspelled.
|
||||
summary: Retrieve a query suggestion for a branching suggestion
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
/api/v2/resources:
|
||||
get:
|
||||
operationId: GetResources
|
||||
|
|
@ -7448,7 +7477,7 @@ paths:
|
|||
|
||||
#### Write endpoints
|
||||
|
||||
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB 3 Cloud Serverless.
|
||||
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB Cloud Serverless.
|
||||
|
||||
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v1/).
|
||||
- Use [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v2/).
|
||||
|
|
@ -7678,10 +7707,9 @@ paths:
|
|||
type: integer
|
||||
default:
|
||||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Write data
|
||||
summary: Write data using the InfluxDB v2 HTTP API
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Write
|
||||
- Write data
|
||||
/legacy/authorizations:
|
||||
servers:
|
||||
- url: /private
|
||||
|
|
@ -7847,8 +7875,7 @@ paths:
|
|||
description: Error processing query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Query
|
||||
- Query data
|
||||
/write:
|
||||
post:
|
||||
operationId: PostLegacyWrite
|
||||
|
|
@ -7876,7 +7903,7 @@ paths:
|
|||
|
||||
#### Write endpoints
|
||||
|
||||
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB 3 Cloud Serverless.
|
||||
The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB Cloud Serverless.
|
||||
|
||||
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v1/).
|
||||
- Use [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v2/).
|
||||
|
|
@ -8011,8 +8038,7 @@ paths:
|
|||
description: Internal server error
|
||||
summary: Write data using the InfluxDB v1 HTTP API
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Write
|
||||
- Write data
|
||||
components:
|
||||
examples:
|
||||
AuthorizationPostRequest:
|
||||
|
|
@ -14756,7 +14782,7 @@ x-tagGroups:
|
|||
- Invokable Scripts
|
||||
- Limits
|
||||
- Organizations
|
||||
- Query
|
||||
- Query data
|
||||
- Resources
|
||||
- Routes
|
||||
- Secrets
|
||||
|
|
@ -14765,4 +14791,4 @@ x-tagGroups:
|
|||
- Templates
|
||||
- Usage
|
||||
- Variables
|
||||
- Write
|
||||
- Write data
|
||||
|
|
|
|||
|
|
@ -6,13 +6,11 @@ extends:
|
|||
x-influxdata-product-name: InfluxDB 3 Clustered
|
||||
|
||||
apis:
|
||||
management@0:
|
||||
root: management/openapi.yml
|
||||
v2@2:
|
||||
root: v2/ref.yml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb3/clustered/api/
|
||||
v1-compatibility@2:
|
||||
root: v1-compatibility/swaggerV1Compat.yml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb3/clustered/api/v1/
|
||||
- /influxdb3/clustered/api/v2/
|
||||
- /influxdb3/clustered/api/v1-compatibility
|
||||
- /influxdb3/clustered/api/v2-compatibility
|
||||
|
|
|
|||
|
|
@ -1,6 +0,0 @@
|
|||
- name: Using the Management API
|
||||
tags:
|
||||
- Authentication
|
||||
- Quickstart
|
||||
- name: All endpoints
|
||||
tags: []
|
||||
|
|
@ -28,250 +28,47 @@ security:
|
|||
- bearerAuthManagementToken: []
|
||||
bearerAuthJwt: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
x-traitTag: true
|
||||
description: |
|
||||
With InfluxDB 3 Clustered, InfluxDB Management API endpoints require the following credential:
|
||||
|
||||
- `Authorization MANAGEMENT_TOKEN`: the `Authorization` HTTP header with a [management token](/influxdb3/clustered/admin/tokens/management/).
|
||||
|
||||
See how to [create a management token](/influxdb3/clustered/admin/tokens/management/).
|
||||
|
||||
By default, management tokens in InfluxDB 3 are short-lived tokens issued by an OAuth2 identity provider that grant a specific user administrative access to your InfluxDB cluster. However, for automation purposes, you can manually create management tokens that authenticate directly with your InfluxDB cluster and do not require human interaction with your identity provider.
|
||||
- name: Database tokens
|
||||
description: Manage database read/write tokens for a cluster
|
||||
- name: Databases
|
||||
description: Manage databases for a cluster
|
||||
- name: Quickstart
|
||||
- name: Quick start
|
||||
x-traitTag: true
|
||||
description: |
|
||||
The following example script shows how to use `curl` to make database and token management requests:
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
```shell
|
||||
#!/bin/bash
|
||||
1. Create a management token using `influxctl token create`.
|
||||
|
||||
# Usage:
|
||||
# Note the leading space in the command below to keep secrets out of the shell history
|
||||
#
|
||||
# ```
|
||||
# MANAGEMENT_TOKEN=<MANAGEMENT_TOKEN> ./scripts/test_http_api_v0_endpoints.sh
|
||||
# ```
|
||||
2. Create a database using the Management API.
|
||||
|
||||
# Env var validation
|
||||
if [ -z "${MANAGEMENT_TOKEN}" ]; then
|
||||
echo "
|
||||
[Error]: ❌
|
||||
\$MANAGEMENT_TOKEN env var is required.
|
||||
"
|
||||
exit 1
|
||||
fi
|
||||
```bash
|
||||
curl -X POST "https://CLUSTER_HOST/api/v0/databases" \
|
||||
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{"name": "sensors"}'
|
||||
```
|
||||
|
||||
HOST="https://cluster-host.com"
|
||||
3. Create a database token for read/write access.
|
||||
|
||||
# Database request functions
|
||||
list_databases () {
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/databases" \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
```bash
|
||||
curl -X POST "https://CLUSTER_HOST/api/v0/tokens" \
|
||||
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{"description": "my token", "permissions": [{"action": "write", "resource": "sensors"}]}'
|
||||
```
|
||||
|
||||
create_database () {
|
||||
local databaseName=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/databases" \
|
||||
--header "Accept: application/json" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
--data '{
|
||||
"name": "'$databaseName'",
|
||||
"maxTables": 75,
|
||||
"maxColumnsPerTable": 90,
|
||||
"retentionPeriod": 600000000000,
|
||||
"partitionTemplate": [
|
||||
{
|
||||
"type": "tag",
|
||||
"value": "abc"
|
||||
},
|
||||
{
|
||||
"type": "bucket",
|
||||
"value": {
|
||||
"tagName": "def",
|
||||
"numberOfBuckets": 5
|
||||
}
|
||||
}
|
||||
]
|
||||
}' \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
4. Write data to InfluxDB Clustered.
|
||||
|
||||
update_database () {
|
||||
local databaseName=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/databases/$databaseName" \
|
||||
--request PATCH \
|
||||
--header "Accept: application/json" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
--data '{
|
||||
"maxTables": 150,
|
||||
"maxColumnsPerTable": 180,
|
||||
"retentionPeriod": 1200000000000
|
||||
}' \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
```bash
|
||||
curl -X POST "https://CLUSTER_HOST/api/v2/write?bucket=sensors&precision=ns" \
|
||||
--header "Authorization: Token DATABASE_TOKEN" \
|
||||
--data-raw "home,room=Kitchen temp=72.0"
|
||||
```
|
||||
|
||||
delete_database () {
|
||||
local databaseName=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/databases/$databaseName" \
|
||||
--request DELETE \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
5. Query data using SQL or InfluxQL with a Flight client or the HTTP API.
|
||||
|
||||
# Token request functions
|
||||
list_tokens () {
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/tokens" \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
create_token () {
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/tokens" \
|
||||
--header "Accept: application/json" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
--data '{
|
||||
"description": "my test token",
|
||||
"permissions": [
|
||||
{
|
||||
"action": "write",
|
||||
"resource": "database_one"
|
||||
},
|
||||
{
|
||||
"action": "read",
|
||||
"resource": "database_two"
|
||||
}
|
||||
]
|
||||
}' \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
get_token () {
|
||||
local token_id=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/tokens/$tokenId" \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
update_token () {
|
||||
local token_id=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/tokens/$tokenId" \
|
||||
--request PATCH \
|
||||
--header "Accept: application/json" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
--data '{
|
||||
"description": "my updated test token",
|
||||
"permissions": [
|
||||
{
|
||||
"action": "database_one",
|
||||
"resource": "read"
|
||||
}
|
||||
]
|
||||
}' \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
delete_token () {
|
||||
local token_id=$1
|
||||
local response=$( \
|
||||
curl \
|
||||
--location "$HOST/api/v0/tokens/$tokenId" \
|
||||
--request DELETE \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Bearer $MANAGEMENT_TOKEN" \
|
||||
)
|
||||
echo "$response"
|
||||
}
|
||||
|
||||
|
||||
# Test database endpoints
|
||||
databaseName="test_database_$RANDOM"
|
||||
|
||||
printf "\n🏗️ Creating database... 🏗️\n\n"
|
||||
response="$(create_database $databaseName)"
|
||||
echo $response | jq
|
||||
printf "\n🏗️ Creating database successful 🏗️\n\n"
|
||||
|
||||
printf "\n⬆️ Updating database... ⬆️\n\n"
|
||||
response="$(update_database $databaseName)"
|
||||
echo $response | jq
|
||||
printf "\n⬆️ Updating database successful ⬆️\n\n"
|
||||
|
||||
printf "\n⬇️ Listing databases... ⬇️\n\n"
|
||||
response="$(list_databases)"
|
||||
echo $response | jq
|
||||
printf "\n⬇️ Listing databases successful ⬇️\n\n"
|
||||
|
||||
printf "\n🗑️ Deleting database... 🗑️\n\n"
|
||||
response="$(delete_database $databaseName)"
|
||||
echo $response | jq
|
||||
printf "\n🗑️ Deleting database successful 🗑️\n\n"
|
||||
|
||||
|
||||
# Test token endpoints
|
||||
printf "\n🏗️ Creating token... 🏗️\n\n"
|
||||
response="$(create_token)"
|
||||
echo $response | jq
|
||||
tokenId=$(echo $response | jq '.id')
|
||||
printf "\n🏗️ Creating token successful 🏗️\n\n"
|
||||
|
||||
printf "\n⬇️ Getting token... ⬇️\n\n"
|
||||
response="$(get_token $tokenId)"
|
||||
echo $response | jq
|
||||
printf "\n⬇️ Getting token successful ⬇️\n\n"
|
||||
|
||||
printf "\n⬆️ Updating token... ⬆️\n\n"
|
||||
response="$(update_token $tokenId)"
|
||||
echo $response | jq
|
||||
printf "\n⬆️ Updating token successful ⬆️\n\n"
|
||||
|
||||
printf "\n📋 Listing tokens... 📋\n\n"
|
||||
response="$(list_tokens)"
|
||||
echo $response | jq
|
||||
printf "\n📋 Listing tokens successful 📋\n\n"
|
||||
|
||||
printf "\n🗑️ Deleting token... 🗑️\n\n"
|
||||
response="$(delete_token $tokenId)"
|
||||
echo $response | jq
|
||||
printf "\n🗑️ Deleting token successful 🗑️\n\n"
|
||||
```
|
||||
For more information, see the
|
||||
[Get started](/influxdb3/clustered/get-started/) guide.
|
||||
- name: Tables
|
||||
description: Manage tables in a database
|
||||
paths:
|
||||
|
|
@ -2031,8 +1828,7 @@ components:
|
|||
x-tagGroups:
|
||||
- name: Using the Management API
|
||||
tags:
|
||||
- Authentication
|
||||
- Quickstart
|
||||
- Quick start
|
||||
- name: All endpoints
|
||||
tags:
|
||||
- Database tokens
|
||||
|
|
|
|||
|
|
@ -1,12 +0,0 @@
|
|||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
- Quick start
|
||||
- Authentication
|
||||
- Headers
|
||||
- Pagination
|
||||
- Response codes
|
||||
- name: All endpoints
|
||||
tags:
|
||||
- Ping
|
||||
- Query
|
||||
- Write
|
||||
|
|
@ -32,49 +32,68 @@ security:
|
|||
- QuerystringAuthentication: []
|
||||
tags:
|
||||
- description: |
|
||||
Use InfluxDB v1 and v2 compatible endpoints to write and query data.
|
||||
|
||||
### Write data
|
||||
|
||||
InfluxDB 3 Clustered provides the following HTTP API endpoints for writing data:
|
||||
|
||||
- **Recommended**: [`/api/v2/write` endpoint](/influxdb3/clustered/api/#operation/PostWrite) for new write workloads or for bringing existing InfluxDB v2 write workloads to InfluxDB 3.
|
||||
- [`/write` endpoint](/influxdb3/clustered/api/#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to InfluxDB 3.
|
||||
- `/api/v2/write` endpoint (recommended) for new write workloads or for
|
||||
bringing existing InfluxDB v2 write workloads to InfluxDB Clustered.
|
||||
- `/write` endpoint for bringing existing InfluxDB v1 write workloads to
|
||||
InfluxDB Clustered.
|
||||
|
||||
Both endpoints accept the same line protocol format and process data in the same way.
|
||||
Both endpoints accept line protocol format and process data the same way.
|
||||
|
||||
### Query data
|
||||
|
||||
InfluxDB 3 Clustered provides the following protocols for executing a query:
|
||||
|
||||
- **Recommended**: _Flight+gRPC_ request that contains an SQL or InfluxQL query. See how to [get started querying InfluxDB using Flight and SQL](/influxdb3/clustered/get-started/query/).
|
||||
- HTTP API [`/query` request](/influxdb3/clustered/api/#operation/GetLegacyQuery) that contains an InfluxQL query.
|
||||
Use this protocol when bringing existing InfluxDB v1 query workloads to InfluxDB 3.
|
||||
- Flight+gRPC request (recommended) that contains an SQL or InfluxQL query.
|
||||
- HTTP API `/query` request that contains an InfluxQL query.
|
||||
Use this protocol for existing InfluxDB v1 query workloads.
|
||||
|
||||
### InfluxDB v2 compatibility
|
||||
|
||||
The HTTP API [`/api/v2/write` endpoint](/influxdb3/clustered/api/#operation/PostWrite) works with the [`Bearer`](#section/Authentication/BearerAuthentication) and [`Token`](#section/Authentication/TokenAuthentication) authentication schemes and existing InfluxDB 2.x tools and code for [writing data](/influxdb3/clustered/write-data/).
|
||||
|
||||
See how to [use the InfluxDB v2 HTTP API with InfluxDB 3 Clustered ](/influxdb3/clustered/guides/api-compatibility/v2/).
|
||||
The `/api/v2/write` endpoint works with Bearer and Token authentication
|
||||
and existing InfluxDB 2.x tools and code.
|
||||
|
||||
### InfluxDB v1 compatibility
|
||||
|
||||
The HTTP API [`/write` endpoint](/influxdb3/clustered/api/#operation/PostLegacyWrite) and [`/query` endpoint](/influxdb3/clustered/api/#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
|
||||
|
||||
See how to [use the InfluxDB v1 HTTP API with InfluxDB 3 Clustered ](/influxdb3/clustered/guides/api-compatibility/v1/).
|
||||
The `/write` and `/query` endpoints work with InfluxDB 1.x username/password
|
||||
authentication and existing InfluxDB 1.x tools and code.
|
||||
name: API compatibility
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API:
|
||||
Authenticate API requests using tokens, basic auth, or query strings.
|
||||
|
||||
| Authentication scheme | Works with |
|
||||
|:-------------------|:-----------|
|
||||
| [Bearer authentication](#section/Authentication/BearerAuthentication) | All endpoints |
|
||||
| [Token authentication](#section/Authentication/TokenAuthentication) | v1, v2 endpoints |
|
||||
| [Basic authentication](#section/Authentication/BasicAuthentication) | v1 endpoints |
|
||||
| [Querystring authentication](#section/Authentication/QuerystringAuthentication) | v1 endpoints |
|
||||
## Token types
|
||||
|
||||
InfluxDB 3 Clustered uses two types of tokens for API authentication:
|
||||
|
||||
| Token type | Used for | How to create |
|
||||
|:-----------|:---------|:--------------|
|
||||
| **Management token** | Management operations (`/api/v0/*`) - manage databases, tables, and database tokens | [`influxctl management create`](/influxdb3/clustered/reference/cli/influxctl/management/create/) |
|
||||
| **Database token** | Data API (`/api/v2/write`, `/query`, etc.) - write and query data | [Database tokens API](/influxdb3/clustered/api/database-tokens/) or [`influxctl token create`](/influxdb3/clustered/reference/cli/influxctl/token/create/) |
|
||||
|
||||
## Authentication schemes
|
||||
|
||||
Choose an authentication scheme based on the endpoint and your workflow:
|
||||
|
||||
| Scheme | Token type | Endpoints | Header format |
|
||||
|:-------|:-----------|:----------|:--------------|
|
||||
| [Bearer](#section/Authentication/BearerAuthentication) | Database | All data endpoints | `Authorization: Bearer DATABASE_TOKEN` |
|
||||
| [Token](#section/Authentication/TokenAuthentication) | Database | v1, v2 endpoints | `Authorization: Token DATABASE_TOKEN` |
|
||||
| [Basic](#section/Authentication/BasicAuthentication) | Database | v1 endpoints | `Authorization: Basic base64(username:DATABASE_TOKEN)` |
|
||||
| [Query string](#section/Authentication/QuerystringAuthentication) | Database | v1 endpoints | `?u=username&p=DATABASE_TOKEN` |
|
||||
|
||||
Management operations (`/api/v0/*`) require a management token in the `Authorization: Bearer` header.
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
name: Authentication
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Parameters for specifying resources in API requests.
|
||||
|
||||
To specify resources, some InfluxDB API endpoints require parameters or
|
||||
properties in the request--for example,
|
||||
writing to a `database` resource.
|
||||
|
|
@ -86,9 +105,6 @@ tags:
|
|||
| `database`, `db` | string | The database name |
|
||||
name: Common parameters
|
||||
x-traitTag: true
|
||||
- name: Data I/O endpoints
|
||||
description: |
|
||||
Write and query data stored in InfluxDB.
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
|
|
@ -98,7 +114,7 @@ tags:
|
|||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `Authorization` | string | The authorization scheme and credential. |
|
||||
| `Authorization` | string | The [authorization scheme and credential](/influxdb/version/api/authentication/). |
|
||||
| `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. |
|
||||
| `Content-Type` | string | The format of the data in the request body. |
|
||||
name: Headers
|
||||
|
|
@ -107,22 +123,48 @@ tags:
|
|||
- description: |
|
||||
Query data stored in a database.
|
||||
|
||||
- HTTP clients can query the v1 [`/query` endpoint](/influxdb3/clustered/api/#operation/GetLegacyQuery)
|
||||
- HTTP clients can query the v1 [`/query` endpoint](/influxdb3/clustered/api/query-data/)
|
||||
using **InfluxQL** and retrieve data in **CSV** or **JSON** format.
|
||||
- The `/api/v2/query` endpoint can't query InfluxDB 3 Clustered.
|
||||
- _Flight + gRPC_ clients can query using **SQL** or **InfluxQL** and retrieve data in **Arrow** format.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Get started querying InfluxDB](/influxdb3/clustered/get-started/query/)
|
||||
- [Execute queries](/influxdb3/clustered/query-data/execute-queries/)
|
||||
name: Query
|
||||
name: Query data
|
||||
x-influxdatadocs-related:
|
||||
- /influxdb3/clustered/get-started/query/
|
||||
- /influxdb3/clustered/query-data/execute-queries/
|
||||
- description: |
|
||||
See the [**Get Started**](/influxdb3/clustered/get-started/) tutorial
|
||||
to get up and running authenticating with tokens, writing to databases, and querying data.
|
||||
Get started with the InfluxDB 3 Clustered API:
|
||||
|
||||
[**InfluxDB API client libraries and Flight clients**](/influxdb3/clustered/reference/client-libraries/)
|
||||
are available to integrate InfluxDB APIs with your application.
|
||||
1. **Create a management token** using [`influxctl management create`](/influxdb3/clustered/reference/cli/influxctl/management/create/).
|
||||
|
||||
2. **Create a database** using the [Databases API](/influxdb3/clustered/api/databases/).
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cluster-host.com/api/v0/databases" \
|
||||
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{"name": "sensors"}'
|
||||
```
|
||||
|
||||
3. **Create a database token** for read/write access.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cluster-host.com/api/v0/tokens" \
|
||||
--header "Authorization: Bearer MANAGEMENT_TOKEN" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{"description": "my token", "permissions": [{"action": "write", "resource": "sensors"}]}'
|
||||
```
|
||||
|
||||
4. **Write data** to InfluxDB 3 Clustered.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://cluster-host.com/api/v2/write?bucket=sensors&precision=ns" \
|
||||
--header "Authorization: Token DATABASE_TOKEN" \
|
||||
--data-raw "home,room=Kitchen temp=72.0"
|
||||
```
|
||||
|
||||
5. **Query data** using SQL or InfluxQL with a [Flight client](/influxdb3/clustered/query-data/execute-queries/flight-sql/) or the HTTP [`/query` endpoint](/influxdb3/clustered/api/query-data/).
|
||||
|
||||
For more information, see the [Get started](/influxdb3/clustered/get-started/) guide.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
|
|
@ -152,7 +194,7 @@ tags:
|
|||
- name: Usage
|
||||
- description: |
|
||||
Write time series data to [databases](/influxdb3/clustered/admin/databases/) using InfluxDB v1 or v2 endpoints.
|
||||
name: Write
|
||||
name: Write data
|
||||
paths:
|
||||
/ping:
|
||||
get:
|
||||
|
|
@ -239,14 +281,12 @@ paths:
|
|||
|
||||
To ensure that InfluxDB Cloud handles writes in the order you request them,
|
||||
wait for a success response (HTTP `2xx` status code) before you send the next request.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Get started writing data](/influxdb3/clustered/get-started/write/)
|
||||
- [Write data](/influxdb3/clustered/write-data/)
|
||||
- [Best practices for writing data](/influxdb3/clustered/write-data/best-practices/)
|
||||
- [Troubleshoot issues writing data](/influxdb3/clustered/write-data/troubleshoot/)
|
||||
operationId: PostWrite
|
||||
x-influxdatadocs-related:
|
||||
- /influxdb3/clustered/get-started/write/
|
||||
- /influxdb3/clustered/write-data/
|
||||
- /influxdb3/clustered/write-data/best-practices/
|
||||
- /influxdb3/clustered/write-data/troubleshoot/
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- description: |
|
||||
|
|
@ -292,10 +332,6 @@ paths:
|
|||
|
||||
- Returns only `application/json` for format and limit errors.
|
||||
- Returns only `text/html` for some quota limit errors.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Troubleshoot issues writing data](/influxdb3/clustered/write-data/troubleshoot/)
|
||||
in: header
|
||||
name: Accept
|
||||
schema:
|
||||
|
|
@ -357,10 +393,6 @@ paths:
|
|||
1. Use [gzip](https://www.gzip.org/) to compress the line protocol data.
|
||||
2. In your request, send the compressed data and the
|
||||
`Content-Encoding: gzip` header.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Best practices for optimizing writes](/influxdb3/clustered/write-data/best-practices/optimize-writes/)
|
||||
required: true
|
||||
responses:
|
||||
'204':
|
||||
|
|
@ -430,10 +462,9 @@ paths:
|
|||
- Returns this error if the server is temporarily unavailable to accept writes due to concurrent request limits or insufficient healthy ingesters.
|
||||
default:
|
||||
$ref: '#/components/responses/GeneralServerError'
|
||||
summary: Write data
|
||||
summary: Write data using the InfluxDB v2 HTTP API
|
||||
tags:
|
||||
- Data I/O endpoints
|
||||
- Write
|
||||
- Write data
|
||||
/query:
|
||||
get:
|
||||
description: Queries InfluxDB using InfluxQL with InfluxDB v1 request and response formats.
|
||||
|
|
@ -569,7 +600,7 @@ paths:
|
|||
description: Error processing query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
tags:
|
||||
- Query
|
||||
- Query data
|
||||
/write:
|
||||
post:
|
||||
operationId: PostLegacyWrite
|
||||
|
|
@ -624,7 +655,7 @@ paths:
|
|||
'400':
|
||||
description: |
|
||||
Data from the batch was rejected and not written. The response body indicates if a partial write occurred or all data was rejected.
|
||||
If a partial write occurred, then some points from the batch are written and queryable.
|
||||
If a partial write occurred, then some points from the batch are written and queryable.
|
||||
The response body contains details about the [rejected points](/influxdb3/clustered/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -684,15 +715,13 @@ paths:
|
|||
|
||||
To ensure that InfluxDB handles writes in the order you request them,
|
||||
wait for a success response (HTTP `2xx` status code) before you send the next request.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Write data with the InfluxDB API](/influxdb3/clustered/get-started/write/)
|
||||
- [Optimize writes to InfluxDB](/influxdb3/clustered/write-data/best-practices/optimize-writes/)
|
||||
- [Troubleshoot issues writing data](/influxdb3/clustered/write-data/troubleshoot/)
|
||||
summary: Write data using the InfluxDB v1 HTTP API
|
||||
tags:
|
||||
- Write
|
||||
- Write data
|
||||
x-influxdatadocs-related:
|
||||
- /influxdb3/clustered/get-started/write/
|
||||
- /influxdb3/clustered/write-data/best-practices/optimize-writes/
|
||||
- /influxdb3/clustered/write-data/troubleshoot/
|
||||
components:
|
||||
parameters:
|
||||
TraceSpan:
|
||||
|
|
@ -1021,9 +1050,7 @@ components:
|
|||
Annotation rows to include in the results.
|
||||
An _annotation_ is metadata associated with an object (column) in the data model.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- See [Annotated CSV annotations](/influxdb3/clustered/reference/syntax/annotated-csv/#annotations) for examples and more information.
|
||||
See [Annotated CSV annotations](/influxdb3/clustered/reference/syntax/annotated-csv/#annotations) for examples and more information.
|
||||
|
||||
For more information about **annotations** in tabular data,
|
||||
see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns).
|
||||
|
|
@ -1787,9 +1814,7 @@ components:
|
|||
|
||||
- Doesn't use `shardGroupDurationsSeconds`.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- InfluxDB [shards and shard groups](/influxdb3/clustered/reference/internals/shards/)
|
||||
For more information, see [shards and shard groups](/influxdb3/clustered/reference/internals/shards/).
|
||||
format: int64
|
||||
type: integer
|
||||
type:
|
||||
|
|
@ -1934,7 +1959,7 @@ components:
|
|||
description: |
|
||||
Use the `Authorization` header with the `Basic` scheme to authenticate v1 API requests.
|
||||
|
||||
Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints in InfluxDB 3.
|
||||
Works with v1 compatibility [`/write`](/influxdb3/clustered/api/write-data/) and [`/query`](/influxdb3/clustered/api/query-data/) endpoints in InfluxDB 3.
|
||||
|
||||
When authenticating requests, InfluxDB 3 checks that the `password` part of the decoded credential is an authorized token
|
||||
and ignores the `username` part of the decoded credential.
|
||||
|
|
@ -1959,10 +1984,8 @@ components:
|
|||
- **`DATABASE_NAME`**: your InfluxDB 3 Clustered database
|
||||
- **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/)
|
||||
- [Manage tokens](/influxdb3/clustered/admin/tokens/)
|
||||
For more information, see [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/)
|
||||
and [Manage tokens](/influxdb3/clustered/admin/tokens/).
|
||||
QuerystringAuthentication:
|
||||
type: apiKey
|
||||
in: query
|
||||
|
|
@ -1970,7 +1993,7 @@ components:
|
|||
description: |
|
||||
Use InfluxDB 1.x API parameters to provide credentials through the query string for v1 API requests.
|
||||
|
||||
Querystring authentication works with v1-compatible [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints.
|
||||
Querystring authentication works with v1-compatible [`/write`](/influxdb3/clustered/api/write-data/) and [`/query`](/influxdb3/clustered/api/query-data/) endpoints.
|
||||
|
||||
When authenticating requests, InfluxDB 3 checks that the `p` (_password_) query parameter is an authorized token
|
||||
and ignores the `u` (_username_) query parameter.
|
||||
|
|
@ -2015,10 +2038,8 @@ components:
|
|||
- **`DATABASE_NAME`**: the database to query
|
||||
- **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/)
|
||||
- [Manage tokens](/influxdb3/clustered/admin/tokens/)
|
||||
For more information, see [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/)
|
||||
and [Manage tokens](/influxdb3/clustered/admin/tokens/).
|
||||
BearerAuthentication:
|
||||
type: http
|
||||
scheme: bearer
|
||||
|
|
@ -2026,7 +2047,7 @@ components:
|
|||
description: |
|
||||
|
||||
Use the OAuth Bearer authentication
|
||||
scheme to provide an authorization token to InfluxDB 3.
|
||||
scheme to provide an authorization token to InfluxDB Clustered.
|
||||
|
||||
Bearer authentication works with all endpoints.
|
||||
|
||||
|
|
@ -2048,9 +2069,9 @@ components:
|
|||
```
|
||||
TokenAuthentication:
|
||||
description: |
|
||||
Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB 3.
|
||||
Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB Clustered.
|
||||
|
||||
The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB 3.
|
||||
The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB Clustered.
|
||||
|
||||
In your API requests, send an `Authorization` header.
|
||||
For the header value, provide the word `Token` followed by a space and a database token.
|
||||
|
|
@ -2075,9 +2096,7 @@ components:
|
|||
--data-binary 'home,room=kitchen temp=72 1463683075'
|
||||
```
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Manage tokens](/influxdb3/clustered/admin/tokens/)
|
||||
For more information, see [Manage tokens](/influxdb3/clustered/admin/tokens/).
|
||||
in: header
|
||||
name: Authorization
|
||||
type: apiKey
|
||||
|
|
@ -2092,5 +2111,5 @@ x-tagGroups:
|
|||
- name: All endpoints
|
||||
tags:
|
||||
- Ping
|
||||
- Query
|
||||
- Write
|
||||
- Query data
|
||||
- Write data
|
||||
|
|
|
|||
|
|
@ -1,15 +0,0 @@
|
|||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
- Quick start
|
||||
- Authentication
|
||||
- Cache data
|
||||
- Common parameters
|
||||
- Response codes
|
||||
- Compatibility endpoints
|
||||
- Database
|
||||
- Processing engine
|
||||
- Server information
|
||||
- Table
|
||||
- Token
|
||||
- Query data
|
||||
- Write data
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,15 +0,0 @@
|
|||
- name: Using the InfluxDB HTTP API
|
||||
tags:
|
||||
- Quick start
|
||||
- Authentication
|
||||
- Cache data
|
||||
- Common parameters
|
||||
- Response codes
|
||||
- Compatibility endpoints
|
||||
- Database
|
||||
- Processing engine
|
||||
- Server information
|
||||
- Table
|
||||
- Token
|
||||
- Query data
|
||||
- Write data
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,94 +0,0 @@
|
|||
module.exports = SetTagGroups;
|
||||
|
||||
const { collect, getName, sortName, isPresent } = require('../../helpers/content-helper.cjs')
|
||||
/**
|
||||
* Returns an object that defines handler functions for:
|
||||
* - Operation nodes
|
||||
* - DefinitionRoot (the root openapi) node
|
||||
* The order of the two functions is significant.
|
||||
* The Operation handler collects tags from the
|
||||
* operation ('get', 'post', etc.) in every path.
|
||||
* The DefinitionRoot handler, executed when
|
||||
* the parser is leaving the root node,
|
||||
* adds custom `tagGroups` content to `x-tagGroups`
|
||||
* and sets the value of `All Endpoints` to the collected tags.
|
||||
*/
|
||||
/** @type {import('@redocly/openapi-cli').OasDecorator} */
|
||||
function SetTagGroups(data) {
|
||||
if(!Array.isArray(data)) {
|
||||
data = [];
|
||||
}
|
||||
|
||||
const ALL_ENDPOINTS = 'All endpoints';
|
||||
/** Tag names used for ad-hoc grouping of Operations and not specific to a resource or path.
|
||||
* For example, these might be useful for UI navigation and filtering, but shouldn't appear
|
||||
* in a list of resource tags.
|
||||
*/
|
||||
const nonResourceTags = [
|
||||
'Data I/O endpoints',
|
||||
'Security and access endpoints',
|
||||
'System information endpoints'
|
||||
];
|
||||
|
||||
const allEndpointsGroup = data.filter(customGroup => customGroup.name === ALL_ENDPOINTS).pop();
|
||||
|
||||
function addAllEndpointTags(tagGroups) {
|
||||
tagGroups.map(grp => {
|
||||
if(grp.name === ALL_ENDPOINTS && !grp.tags.length) {
|
||||
grp.tags = endpointTags;
|
||||
}
|
||||
return grp;
|
||||
})
|
||||
}
|
||||
|
||||
let tags = [];
|
||||
/** Collect tags for each operation and convert string tags to object tags. **/
|
||||
return {
|
||||
DefinitionRoot: {
|
||||
Operation: {
|
||||
leave(op, ctx) {
|
||||
let opTags = op.tags?.map(
|
||||
function(t) {
|
||||
return typeof t === 'string' ? { name: t } : t;
|
||||
}
|
||||
) || [];
|
||||
|
||||
const { parent, key } = ctx;
|
||||
if(allEndpointsGroup?.tags.length) {
|
||||
opTags.forEach(
|
||||
function(t) {
|
||||
if(!isPresent(allEndpointsGroup.tags, t) && !isPresent(nonResourceTags, t)) {
|
||||
/** If a custom allEndpointsGroup is defined and the current Operation
|
||||
* contains a tag not specified in allEndpointsGroup,
|
||||
* then delete the Operation from the doc so that it doesn't appear in other tags.
|
||||
*/
|
||||
delete parent[key];
|
||||
return;
|
||||
}
|
||||
}
|
||||
)
|
||||
}
|
||||
|
||||
tags = collect(tags, opTags);
|
||||
}
|
||||
},
|
||||
leave(root) {
|
||||
root.tags = root.tags || [];
|
||||
root.tags = collect(root.tags, tags)
|
||||
.sort((a, b) => sortName(a, b));
|
||||
|
||||
endpointTags = root.tags
|
||||
.filter(t => !t['x-traitTag'])
|
||||
.filter(t => !isPresent(nonResourceTags, t))
|
||||
.map(t => getName(t));
|
||||
|
||||
/** In Redoc, if x-tagGroups is present, a tag (and its paths)
|
||||
* must be assigned to an x-tagGroup in order to display. */
|
||||
if(data.length) {
|
||||
addAllEndpointTags(data);
|
||||
root['x-tagGroups'] = data;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
|
@ -15,10 +15,8 @@ function getVersioned(filename) {
|
|||
|
||||
const info = () => getVersioned('info.yml');
|
||||
const servers = () => getVersioned('servers.yml');
|
||||
const tagGroups = () => getVersioned('tag-groups.yml');
|
||||
|
||||
module.exports = {
|
||||
info,
|
||||
servers,
|
||||
tagGroups,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
const {info, servers, tagGroups} = require('./docs-content.cjs');
|
||||
const {info, servers} = require('./docs-content.cjs');
|
||||
const ReportTags = require('./rules/report-tags.cjs');
|
||||
const ValidateServersUrl = require('./rules/validate-servers-url.cjs');
|
||||
const RemovePrivatePaths = require('./decorators/paths/remove-private-paths.cjs');
|
||||
|
|
@ -7,7 +7,6 @@ const ReplaceShortcodes = require('./decorators/replace-shortcodes.cjs');
|
|||
const SetInfo = require('./decorators/set-info.cjs');
|
||||
const DeleteServers = require('./decorators/servers/delete-servers.cjs');
|
||||
const SetServers = require('./decorators/servers/set-servers.cjs');
|
||||
const SetTagGroups = require('./decorators/tags/set-tag-groups.cjs');
|
||||
const StripVersionPrefix = require('./decorators/paths/strip-version-prefix.cjs');
|
||||
const StripTrailingSlash = require('./decorators/paths/strip-trailing-slash.cjs');
|
||||
|
||||
|
|
@ -31,7 +30,6 @@ const decorators = {
|
|||
'strip-version-prefix': StripVersionPrefix,
|
||||
'strip-trailing-slash': StripTrailingSlash,
|
||||
'set-info': () => SetInfo(info()),
|
||||
'set-tag-groups': () => SetTagGroups(tagGroups()),
|
||||
'replace-docs-url-shortcode': ReplaceShortcodes().docsUrl
|
||||
}
|
||||
};
|
||||
|
|
@ -52,7 +50,6 @@ module.exports = {
|
|||
'docs/strip-version-prefix': 'error',
|
||||
'docs/strip-trailing-slash': 'error',
|
||||
'docs/set-info': 'error',
|
||||
'docs/set-tag-groups': 'error',
|
||||
'docs/replace-docs-url-shortcode': 'error'
|
||||
},
|
||||
},
|
||||
|
|
|
|||
|
|
@ -0,0 +1,390 @@
|
|||
# API Documentation Generation Scripts
|
||||
|
||||
TypeScript-based scripts for generating Hugo data files and content pages from OpenAPI specifications.
|
||||
|
||||
## Overview
|
||||
|
||||
These scripts convert OpenAPI v3 specifications into Hugo-compatible data files and content pages for all InfluxDB products.
|
||||
|
||||
### What Gets Generated
|
||||
|
||||
For each product, the scripts generate:
|
||||
|
||||
1. **OpenAPI Spec Copies** (static directory):
|
||||
- `influxdb-{product}.yml` - YAML version of the spec
|
||||
- `influxdb-{product}.json` - JSON version of the spec
|
||||
|
||||
2. **Path Group Fragments** (static/openapi/{product}/paths/):
|
||||
- Separate YAML and JSON files for each API path group
|
||||
- Example: `ref-api-v2-buckets.yaml` and `ref-api-v2-buckets.json`
|
||||
|
||||
3. **Article Metadata** (data/article-data/influxdb/{product}/):
|
||||
- `articles.yml` - Hugo data file with article metadata
|
||||
- `articles.json` - JSON version for programmatic access
|
||||
|
||||
4. **Hugo Content Pages** (content/{product}/api/):
|
||||
- Markdown files generated from article data
|
||||
- One page per API path group
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Build Scripts
|
||||
|
||||
Compile TypeScript to JavaScript (required before running):
|
||||
|
||||
```bash
|
||||
yarn build:api-scripts
|
||||
```
|
||||
|
||||
### Generate API Pages
|
||||
|
||||
**Generate all products:**
|
||||
|
||||
```bash
|
||||
yarn build:api-pages
|
||||
```
|
||||
|
||||
**Generate specific product(s):**
|
||||
|
||||
```bash
|
||||
yarn build:api-pages:product cloud-v2
|
||||
yarn build:api-pages:product cloud-v2 oss-v2
|
||||
```
|
||||
|
||||
## Supported Products
|
||||
|
||||
| Product ID | Description | Spec File | Content Path |
|
||||
| ---------------------- | ------------------------- | ------------------------------------------------ | -------------------------------------------- |
|
||||
| `cloud-v2` | InfluxDB Cloud (v2 API) | `api-docs/cloud/v2/ref.yml` | `content/influxdb/cloud/api/v2` |
|
||||
| `oss-v2` | InfluxDB OSS v2 | `api-docs/v2/ref.yml` | `content/influxdb/v2/api/v2` |
|
||||
| `influxdb3-core` | InfluxDB 3 Core | `api-docs/influxdb3/core/v3/ref.yml` | `content/influxdb3/core/reference/api` |
|
||||
| `influxdb3-enterprise` | InfluxDB 3 Enterprise | `api-docs/influxdb3/enterprise/v3/ref.yml` | `content/influxdb3/enterprise/reference/api` |
|
||||
| `cloud-dedicated` | InfluxDB Cloud Dedicated | `api-docs/influxdb3/cloud-dedicated/v2/ref.yml` | `content/influxdb/cloud-dedicated/api` |
|
||||
| `cloud-serverless` | InfluxDB Cloud Serverless | `api-docs/influxdb3/cloud-serverless/v2/ref.yml` | `content/influxdb/cloud-serverless/api` |
|
||||
| `clustered` | InfluxDB Clustered | `api-docs/influxdb3/clustered/v2/ref.yml` | `content/influxdb/clustered/api` |
|
||||
|
||||
## Architecture
|
||||
|
||||
### TypeScript Files
|
||||
|
||||
```
|
||||
api-docs/scripts/
|
||||
├── tsconfig.json # TypeScript configuration
|
||||
├── generate-openapi-articles.ts # Main orchestration script
|
||||
└── openapi-paths-to-hugo-data/
|
||||
├── index.ts # Core conversion logic
|
||||
└── package.json # Module dependencies
|
||||
```
|
||||
|
||||
### Compiled JavaScript
|
||||
|
||||
After running `yarn build:api-scripts`, compiled files are in:
|
||||
|
||||
```
|
||||
api-docs/scripts/dist/
|
||||
├── generate-openapi-articles.js
|
||||
├── generate-openapi-articles.d.ts
|
||||
└── openapi-paths-to-hugo-data/
|
||||
├── index.js
|
||||
└── index.d.ts
|
||||
```
|
||||
|
||||
## Script Details
|
||||
|
||||
### generate-openapi-articles.ts
|
||||
|
||||
Main orchestration script that processes products.
|
||||
|
||||
**For each product, it:**
|
||||
|
||||
1. Runs `getswagger.sh` to fetch/bundle the OpenAPI spec
|
||||
2. Copies spec to `static/openapi/influxdb-{product}.yml`
|
||||
3. Generates JSON version at `static/openapi/influxdb-{product}.json`
|
||||
4. Generates path group fragments (YAML and JSON)
|
||||
5. Creates article metadata (YAML and JSON)
|
||||
6. Generates Hugo content pages
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
node api-docs/scripts/dist/generate-openapi-articles.js [product-ids...]
|
||||
|
||||
# Examples:
|
||||
node api-docs/scripts/dist/generate-openapi-articles.js # All products
|
||||
node api-docs/scripts/dist/generate-openapi-articles.js cloud-v2 # Single product
|
||||
node api-docs/scripts/dist/generate-openapi-articles.js cloud-v2 oss-v2 # Multiple products
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
📋 Processing all products...
|
||||
|
||||
================================================================================
|
||||
Processing InfluxDB Cloud (v2 API)
|
||||
================================================================================
|
||||
|
||||
Fetching OpenAPI spec for cloud-v2...
|
||||
✓ Copied spec to static/openapi/influxdb-cloud-v2.yml
|
||||
✓ Generated JSON spec at static/openapi/influxdb-cloud-v2.json
|
||||
|
||||
Generating OpenAPI path files in static/openapi/influxdb-cloud-v2/paths....
|
||||
Generated: ref-api-v2-buckets.yaml and ref-api-v2-buckets.json
|
||||
...
|
||||
|
||||
Generating OpenAPI article data in data/article-data/influxdb/cloud-v2...
|
||||
Generated 32 articles in data/article-data/influxdb/cloud-v2
|
||||
|
||||
✅ Successfully processed InfluxDB Cloud (v2 API)
|
||||
```
|
||||
|
||||
### openapi-paths-to-hugo-data/index.ts
|
||||
|
||||
Core conversion library that processes OpenAPI specs.
|
||||
|
||||
**Key Functions:**
|
||||
|
||||
- `generateHugoData(options)` - Main entry point
|
||||
- `writePathOpenapis()` - Groups paths and writes fragments
|
||||
- `createArticleDataForPathGroup()` - Generates article metadata
|
||||
|
||||
**Path Grouping Logic:**
|
||||
|
||||
Paths are grouped by their base path (first 3-4 segments, excluding placeholders):
|
||||
|
||||
```
|
||||
/api/v2/buckets → api-v2-buckets
|
||||
/api/v2/buckets/{id} → api-v2-buckets (same group)
|
||||
/api/v2/authorizations → api-v2-authorizations
|
||||
```
|
||||
|
||||
**Output Formats:**
|
||||
|
||||
- **YAML**: Hugo-compatible data files
|
||||
- **JSON**: Programmatic access and tooling
|
||||
|
||||
## Development
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js >= 16.0.0
|
||||
- Yarn package manager
|
||||
- TypeScript installed (via root package.json)
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Install dependencies (from repo root)
|
||||
yarn install
|
||||
|
||||
# Or install in the openapi-paths-to-hugo-data module
|
||||
cd api-docs/scripts/openapi-paths-to-hugo-data
|
||||
yarn install
|
||||
```
|
||||
|
||||
### TypeScript Configuration
|
||||
|
||||
The scripts use a dedicated `tsconfig.json` with CommonJS output:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2021",
|
||||
"module": "CommonJS",
|
||||
"outDir": "./dist",
|
||||
"strict": true,
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Making Changes
|
||||
|
||||
1. Edit TypeScript files in `api-docs/scripts/`
|
||||
2. Compile: `yarn build:api-scripts`
|
||||
3. Test: `yarn build:api-pages:product cloud-v2`
|
||||
|
||||
### Watch Mode
|
||||
|
||||
For active development:
|
||||
|
||||
```bash
|
||||
cd api-docs/scripts/openapi-paths-to-hugo-data
|
||||
yarn build:watch
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Test Example
|
||||
|
||||
```javascript
|
||||
const converter = require('./api-docs/scripts/dist/openapi-paths-to-hugo-data/index.js');
|
||||
|
||||
converter.generateHugoData({
|
||||
specFile: 'api-docs/influxdb/cloud/v2/ref.yml',
|
||||
dataOutPath: './test-output/paths',
|
||||
articleOutPath: './test-output/articles'
|
||||
});
|
||||
```
|
||||
|
||||
### Verify Output
|
||||
|
||||
After generation, check:
|
||||
|
||||
1. **Path fragments exist:**
|
||||
```bash
|
||||
ls -l static/openapi/influxdb-cloud-v2/paths/
|
||||
```
|
||||
|
||||
2. **Both formats generated:**
|
||||
```bash
|
||||
ls -l static/openapi/influxdb-cloud-v2/paths/*.{yaml,json}
|
||||
```
|
||||
|
||||
3. **Article data created:**
|
||||
```bash
|
||||
cat data/article-data/influxdb/cloud-v2/articles.yml
|
||||
cat data/article-data/influxdb/cloud-v2/articles.json
|
||||
```
|
||||
|
||||
4. **Hugo pages generated:**
|
||||
```bash
|
||||
ls -l content/influxdb/cloud/api/v2/
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### TypeScript Compilation Errors
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
rm -rf api-docs/scripts/dist
|
||||
yarn build:api-scripts
|
||||
```
|
||||
|
||||
### Missing Type Definitions
|
||||
|
||||
```bash
|
||||
cd api-docs/scripts/openapi-paths-to-hugo-data
|
||||
yarn add --dev @types/js-yaml @types/node
|
||||
```
|
||||
|
||||
### Spec File Not Found
|
||||
|
||||
Make sure to run `getswagger.sh` first:
|
||||
|
||||
```bash
|
||||
cd api-docs
|
||||
./getswagger.sh cloud-v2 -B
|
||||
```
|
||||
|
||||
### Path Grouping Issues
|
||||
|
||||
The script groups paths by their first 3-4 segments. If you need different grouping:
|
||||
|
||||
1. Edit `writePathOpenapis()` in `openapi-paths-to-hugo-data/index.ts`
|
||||
2. Modify the `key.slice(0, 4)` logic
|
||||
3. Rebuild: `yarn build:api-scripts`
|
||||
|
||||
## Migration from JavaScript
|
||||
|
||||
The original JavaScript files are preserved for reference:
|
||||
|
||||
- `api-docs/scripts/generate-openapi-articles.js` (original)
|
||||
- `api-docs/scripts/openapi-paths-to-hugo-data/index.js` (original)
|
||||
|
||||
### Key Improvements
|
||||
|
||||
1. **TypeScript**: Full type safety and IDE support
|
||||
2. **Dual Formats**: Generates both YAML and JSON
|
||||
3. **All Products**: Includes all 7 InfluxDB products
|
||||
4. **Better Errors**: Clear error messages with product validation
|
||||
5. **CLI Arguments**: Support for processing specific products
|
||||
6. **Comprehensive Logging**: Progress indicators and status messages
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **API Docs README**: `api-docs/README.md` - Complete API documentation workflow
|
||||
- **OpenAPI Plugins**: `api-docs/openapi/plugins/` - Custom processing plugins
|
||||
- **Hugo Data to Pages**: `hugo-data-to-pages/` - Page generation from data files
|
||||
|
||||
## Examples
|
||||
|
||||
### Generate Only Cloud Products
|
||||
|
||||
```bash
|
||||
yarn build:api-pages:product cloud-v2 cloud-dedicated cloud-serverless
|
||||
```
|
||||
|
||||
### Generate Only InfluxDB 3 Products
|
||||
|
||||
```bash
|
||||
yarn build:api-pages:product influxdb3-core influxdb3-enterprise
|
||||
```
|
||||
|
||||
### Process Single Product Manually
|
||||
|
||||
```bash
|
||||
# Compile first
|
||||
yarn build:api-scripts
|
||||
|
||||
# Run for specific product
|
||||
node api-docs/scripts/dist/generate-openapi-articles.js oss-v2
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### generateHugoData(options)
|
||||
|
||||
Generate Hugo data files from an OpenAPI specification.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
- `options.specFile` (string) - Path to the OpenAPI spec file
|
||||
- `options.dataOutPath` (string) - Output path for OpenAPI path fragments
|
||||
- `options.articleOutPath` (string) - Output path for article metadata
|
||||
|
||||
**Example:**
|
||||
|
||||
```javascript
|
||||
const { generateHugoData } = require('./api-docs/scripts/dist/openapi-paths-to-hugo-data/index.js');
|
||||
|
||||
generateHugoData({
|
||||
specFile: 'api-docs/influxdb/cloud/v2/ref.yml',
|
||||
dataOutPath: 'static/openapi/influxdb-cloud-v2/paths',
|
||||
articleOutPath: 'data/article-data/influxdb/cloud-v2'
|
||||
});
|
||||
```
|
||||
|
||||
### productConfigs
|
||||
|
||||
Map of product configurations exported from `generate-openapi-articles.ts`.
|
||||
|
||||
**Type:**
|
||||
|
||||
```typescript
|
||||
type ProductConfig = {
|
||||
specFile: string; // Path to OpenAPI spec
|
||||
pagesDir: string; // Hugo content directory
|
||||
description?: string; // Product description
|
||||
};
|
||||
|
||||
const productConfigs: Record<string, ProductConfig>;
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
|
||||
```javascript
|
||||
const { productConfigs } = require('./api-docs/scripts/dist/generate-openapi-articles.js');
|
||||
|
||||
console.log(productConfigs['cloud-v2']);
|
||||
// {
|
||||
// specFile: 'api-docs/cloud/v2/ref.yml',
|
||||
// pagesDir: 'content/influxdb/cloud/api/v2',
|
||||
// description: 'InfluxDB Cloud (v2 API)'
|
||||
// }
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Same as parent docs-v2 repository (MIT).
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,14 @@
|
|||
{
|
||||
"name": "openapi-paths-to-hugo-data",
|
||||
"version": "1.0.0",
|
||||
"description": "Convert OpenAPI specifications to Hugo data files for API documentation",
|
||||
"main": "index.js",
|
||||
"type": "commonjs",
|
||||
"dependencies": {
|
||||
"js-yaml": "^4.1.1"
|
||||
},
|
||||
"devDependencies": {},
|
||||
"scripts": {},
|
||||
"author": "InfluxData",
|
||||
"license": "MIT"
|
||||
}
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
|
||||
# yarn lockfile v1
|
||||
|
||||
|
||||
"@types/js-yaml@^4.0.9":
|
||||
version "4.0.9"
|
||||
resolved "https://registry.yarnpkg.com/@types/js-yaml/-/js-yaml-4.0.9.tgz#cd82382c4f902fed9691a2ed79ec68c5898af4c2"
|
||||
integrity sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==
|
||||
|
||||
"@types/node@^24.10.1":
|
||||
version "24.10.1"
|
||||
resolved "https://registry.yarnpkg.com/@types/node/-/node-24.10.1.tgz#91e92182c93db8bd6224fca031e2370cef9a8f01"
|
||||
integrity sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ==
|
||||
dependencies:
|
||||
undici-types "~7.16.0"
|
||||
|
||||
argparse@^2.0.1:
|
||||
version "2.0.1"
|
||||
resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38"
|
||||
integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==
|
||||
|
||||
js-yaml@^4.1.0:
|
||||
version "4.1.1"
|
||||
resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.1.tgz#854c292467705b699476e1a2decc0c8a3458806b"
|
||||
integrity sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==
|
||||
dependencies:
|
||||
argparse "^2.0.1"
|
||||
|
||||
undici-types@~7.16.0:
|
||||
version "7.16.0"
|
||||
resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-7.16.0.tgz#ffccdff36aea4884cbfce9a750a0580224f58a46"
|
||||
integrity sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2021",
|
||||
"lib": ["ES2021"],
|
||||
"module": "CommonJS",
|
||||
"moduleResolution": "node",
|
||||
"outDir": "./dist",
|
||||
"rootDir": ".",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"resolveJsonModule": true,
|
||||
"declaration": true,
|
||||
"sourceMap": true,
|
||||
"types": ["node"]
|
||||
},
|
||||
"include": [
|
||||
"**/*.ts"
|
||||
],
|
||||
"exclude": [
|
||||
"node_modules",
|
||||
"dist"
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: InfluxDB HTTP API
|
||||
description: >-
|
||||
Use the InfluxDB HTTP API to write data, query data, and manage databases,
|
||||
tables, and tokens.
|
||||
weight: 104
|
||||
type: api
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
||||
Use the {{% product-name %}} HTTP API to write data, query data, and manage databases, tables, and tokens.
|
||||
|
||||
{{< children >}}
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
title: All endpoints
|
||||
description: View all API endpoints sorted by path.
|
||||
type: api
|
||||
layout: all-endpoints
|
||||
weight: 999
|
||||
isAllEndpoints: true
|
||||
menu:
|
||||
enterprise_influxdb_v1:
|
||||
name: All endpoints
|
||||
parent: InfluxDB HTTP API
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
||||
All {{% product-name %}} API endpoints, sorted by path.
|
||||
|
|
@ -0,0 +1,84 @@
|
|||
---
|
||||
title: Authentication
|
||||
description: >-
|
||||
InfluxDB Enterprise v1 supports multiple authentication methods:
|
||||
|
||||
|
||||
### Basic Authentication
|
||||
|
||||
```bash
|
||||
|
||||
curl -u username:password http://localhost:8086/query?q=SHOW+DATABASES
|
||||
|
||||
```
|
||||
|
||||
|
||||
### Query String Authentication
|
||||
|
||||
```bash
|
||||
|
||||
curl "http://localhost:8086/query?u=username&p=password&q=SHOW+DATABASES"
|
||||
|
||||
```
|
||||
|
||||
|
||||
### Token Authentication (v2-compatible)
|
||||
|
||||
For v2-compatible endpoints, use the Token scheme:
|
||||
|
||||
```bash
|
||||
|
||||
curl -H "Authorization: Token username:password"
|
||||
http://localhost:8086/api/v2/query
|
||||
|
||||
```
|
||||
type: api
|
||||
layout: single
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-authentication.yaml
|
||||
weight: 100
|
||||
tag: Authentication
|
||||
isConceptual: true
|
||||
menuGroup: Concepts
|
||||
tagDescription: >-
|
||||
InfluxDB Enterprise v1 supports multiple authentication methods:
|
||||
|
||||
|
||||
### Basic Authentication
|
||||
|
||||
```bash
|
||||
|
||||
curl -u username:password http://localhost:8086/query?q=SHOW+DATABASES
|
||||
|
||||
```
|
||||
|
||||
|
||||
### Query String Authentication
|
||||
|
||||
```bash
|
||||
|
||||
curl "http://localhost:8086/query?u=username&p=password&q=SHOW+DATABASES"
|
||||
|
||||
```
|
||||
|
||||
|
||||
### Token Authentication (v2-compatible)
|
||||
|
||||
For v2-compatible endpoints, use the Token scheme:
|
||||
|
||||
```bash
|
||||
|
||||
curl -H "Authorization: Token username:password"
|
||||
http://localhost:8086/api/v2/query
|
||||
|
||||
```
|
||||
showSecuritySchemes: true
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
title: Debug
|
||||
description: >-
|
||||
Debugging and profiling endpoints for troubleshooting and performance
|
||||
analysis.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: /openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-debug.yaml
|
||||
weight: 100
|
||||
tag: Debug
|
||||
isConceptual: false
|
||||
menuGroup: Other
|
||||
operations:
|
||||
- operationId: GetDebugPprof
|
||||
method: GET
|
||||
path: /debug/pprof
|
||||
summary: Get profiling index
|
||||
tags:
|
||||
- Debug
|
||||
- operationId: GetDebugPprofProfile
|
||||
method: GET
|
||||
path: /debug/pprof/{profile}
|
||||
summary: Get profile data
|
||||
tags:
|
||||
- Debug
|
||||
- operationId: GetDebugPprofAll
|
||||
method: GET
|
||||
path: /debug/pprof/all
|
||||
summary: Get all profiles archive
|
||||
tags:
|
||||
- Debug
|
||||
- operationId: GetDebugRequests
|
||||
method: GET
|
||||
path: /debug/requests
|
||||
summary: Track HTTP requests
|
||||
tags:
|
||||
- Debug
|
||||
- operationId: GetDebugVars
|
||||
method: GET
|
||||
path: /debug/vars
|
||||
summary: Get server statistics
|
||||
tags:
|
||||
- Debug
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
title: Query
|
||||
description: |-
|
||||
Query data using InfluxQL. The `/query` endpoint supports both read queries
|
||||
(SELECT, SHOW) and write queries (CREATE, DROP, ALTER, etc.).
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: /openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-query.yaml
|
||||
weight: 100
|
||||
tag: Query
|
||||
isConceptual: false
|
||||
menuGroup: Other
|
||||
operations:
|
||||
- operationId: GetQuery
|
||||
method: GET
|
||||
path: /query
|
||||
summary: Query data (GET)
|
||||
tags:
|
||||
- Query
|
||||
- operationId: PostQuery
|
||||
method: POST
|
||||
path: /query
|
||||
summary: Query data (POST)
|
||||
tags:
|
||||
- Query
|
||||
- operationId: PostApiV2Query
|
||||
method: POST
|
||||
path: /api/v2/query
|
||||
summary: Query with Flux (v2 compatible)
|
||||
tags:
|
||||
- Query
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
title: System Information
|
||||
description: Endpoints for checking server status, health, and version information.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-system-information.yaml
|
||||
weight: 100
|
||||
tag: System Information
|
||||
isConceptual: false
|
||||
menuGroup: Other
|
||||
operations:
|
||||
- operationId: GetPing
|
||||
method: GET
|
||||
path: /ping
|
||||
summary: Check server status
|
||||
tags:
|
||||
- System Information
|
||||
- operationId: HeadPing
|
||||
method: HEAD
|
||||
path: /ping
|
||||
summary: Check server status (HEAD)
|
||||
tags:
|
||||
- System Information
|
||||
- operationId: GetHealth
|
||||
method: GET
|
||||
path: /health
|
||||
summary: Check server health
|
||||
tags:
|
||||
- System Information
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: v2 Compatibility
|
||||
description: |-
|
||||
InfluxDB 2.x API compatibility endpoints. These endpoints allow you to use
|
||||
InfluxDB 2.x client libraries with InfluxDB Enterprise 1.8+.
|
||||
|
||||
Use the `Token` scheme with v1.x credentials:
|
||||
```
|
||||
Authorization: Token username:password
|
||||
```
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-v2-compatibility.yaml
|
||||
weight: 100
|
||||
tag: v2 Compatibility
|
||||
isConceptual: false
|
||||
menuGroup: Other
|
||||
operations:
|
||||
- operationId: GetHealth
|
||||
method: GET
|
||||
path: /health
|
||||
summary: Check server health
|
||||
tags:
|
||||
- v2 Compatibility
|
||||
- operationId: PostApiV2Query
|
||||
method: POST
|
||||
path: /api/v2/query
|
||||
summary: Query with Flux (v2 compatible)
|
||||
tags:
|
||||
- v2 Compatibility
|
||||
- operationId: PostApiV2Write
|
||||
method: POST
|
||||
path: /api/v2/write
|
||||
summary: Write data (v2 compatible)
|
||||
tags:
|
||||
- v2 Compatibility
|
||||
- operationId: GetApiV2Buckets
|
||||
method: GET
|
||||
path: /api/v2/buckets
|
||||
summary: List buckets (v2 compatible)
|
||||
tags:
|
||||
- v2 Compatibility
|
||||
- operationId: PostApiV2Buckets
|
||||
method: POST
|
||||
path: /api/v2/buckets
|
||||
summary: Create bucket (v2 compatible)
|
||||
tags:
|
||||
- v2 Compatibility
|
||||
- operationId: DeleteApiV2BucketsBucketID
|
||||
method: DELETE
|
||||
path: /api/v2/buckets/{bucketID}
|
||||
summary: Delete bucket (v2 compatible)
|
||||
tags:
|
||||
- v2 Compatibility
|
||||
- operationId: PostApiV2Delete
|
||||
method: POST
|
||||
path: /api/v2/delete
|
||||
summary: Delete data (v2 compatible)
|
||||
tags:
|
||||
- v2 Compatibility
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
title: Write
|
||||
description: >-
|
||||
Write time series data using InfluxDB line protocol.
|
||||
|
||||
|
||||
**Enterprise Feature**: Use the `consistency` parameter to control write
|
||||
consistency
|
||||
|
||||
across cluster nodes.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: /openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-write.yaml
|
||||
weight: 100
|
||||
tag: Write
|
||||
isConceptual: false
|
||||
menuGroup: Other
|
||||
operations:
|
||||
- operationId: PostWrite
|
||||
method: POST
|
||||
path: /write
|
||||
summary: Write data
|
||||
tags:
|
||||
- Write
|
||||
- operationId: PostApiV2Write
|
||||
method: POST
|
||||
path: /api/v2/write
|
||||
summary: Write data (v2 compatible)
|
||||
tags:
|
||||
- Write
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
Loading…
Reference in New Issue