refactor(api-docs): flatten v3 dirs, rewrite build pipeline, add --static-only mode
- Flatten Core/Enterprise v3/ subdirectories to product root - Rewrite generate-api-docs.sh as clean 3-step pipeline: post-process-specs → Redoc HTML → static spec downloads - Add --static-only flag to generate-openapi-articles.ts - Remove circular getswagger.sh call from generate-openapi-articles.ts - Remove dead execCommand function and --skip-fetch flag - Apply post-processed tag enrichments to all spec filespull/6942/head
Jason Stirnaman
parent
160b308afa
commit
e2f4d80014
|
|
@ -27,6 +27,8 @@ info:
|
|||
license:
|
||||
name: Proprietary
|
||||
url: https://www.influxdata.com/legal/slsa/
|
||||
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.
|
||||
servers:
|
||||
- url: http://localhost:8086
|
||||
description: Local InfluxDB Enterprise data node
|
||||
|
|
@ -35,50 +37,18 @@ security:
|
|||
- QueryAuth: []
|
||||
tags:
|
||||
- name: System Information
|
||||
description: |
|
||||
Endpoints for checking server status, health, and version information.
|
||||
description: Check server status, health, and version information for an InfluxDB Enterprise v1 instance.
|
||||
- name: Query
|
||||
description: |
|
||||
Query data using InfluxQL. The `/query` endpoint supports both read queries
|
||||
(SELECT, SHOW) and write queries (CREATE, DROP, ALTER, etc.).
|
||||
description: Query data using InfluxQL via the `/query` endpoint, supporting both read queries (SELECT, SHOW) and management queries (CREATE, DROP, ALTER).
|
||||
- name: Write
|
||||
description: |
|
||||
Write time series data using InfluxDB line protocol.
|
||||
|
||||
**Enterprise Feature**: Use the `consistency` parameter to control write consistency
|
||||
across cluster nodes.
|
||||
description: Write time series data to InfluxDB Enterprise v1 in line protocol format using the `/write` endpoint. Use the `consistency` parameter to control write consistency across cluster nodes.
|
||||
- name: Debug
|
||||
description: |
|
||||
Debugging and profiling endpoints for troubleshooting and performance analysis.
|
||||
description: Access debugging and profiling endpoints for troubleshooting and performance analysis of an InfluxDB Enterprise v1 instance.
|
||||
- name: 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
|
||||
```
|
||||
description: InfluxDB v2-compatible API endpoints that allow InfluxDB 2.x client libraries to work with InfluxDB Enterprise 1.8+, using the Token authentication scheme with v1 credentials.
|
||||
- name: Authentication
|
||||
x-traitTag: true
|
||||
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
|
||||
```
|
||||
description: Authenticate API requests to InfluxDB Enterprise v1 using basic authentication, query string credentials, or the v2-compatible token scheme.
|
||||
paths:
|
||||
/ping:
|
||||
get:
|
||||
|
|
|
|||
|
|
@ -1,16 +1,27 @@
|
|||
#!/bin/bash
|
||||
|
||||
# Generate API reference documentation for all InfluxDB products.
|
||||
#
|
||||
# Pipeline:
|
||||
# 1. post-process-specs.ts — apply info/servers overlays + tag configs
|
||||
# 2. generateRedocHtml — generate Redoc HTML pages with Hugo frontmatter
|
||||
# 3. generate-openapi-articles.js --static-only — copy specs to static/openapi/
|
||||
#
|
||||
# Specs must already be fetched and bundled (via getswagger.sh) before running.
|
||||
#
|
||||
# Usage:
|
||||
# sh generate-api-docs.sh # Generate all products
|
||||
# sh generate-api-docs.sh -c # Only regenerate specs that differ from master
|
||||
|
||||
set -e
|
||||
|
||||
function showHelp {
|
||||
echo "Usage: generate.sh <options>"
|
||||
echo "Commands:"
|
||||
echo "-c) Regenerate changed files. To save time in development, only regenerates files that differ from the master branch."
|
||||
echo "-h) Show this help message."
|
||||
echo "Usage: generate-api-docs.sh <options>"
|
||||
echo "Options:"
|
||||
echo " -c Regenerate only changed files (diff against master)"
|
||||
echo " -h Show this help message"
|
||||
}
|
||||
|
||||
# Get arguments
|
||||
|
||||
generate_changed=1
|
||||
|
||||
while getopts "hc" opt; do
|
||||
|
|
@ -32,180 +43,187 @@ while getopts "hc" opt; do
|
|||
showHelp
|
||||
exit 22
|
||||
;;
|
||||
esac
|
||||
esac
|
||||
done
|
||||
|
||||
function generateHtml {
|
||||
# ---------------------------------------------------------------------------
|
||||
# Step 1: Post-process specs (info/servers overlays + tag configs)
|
||||
# ---------------------------------------------------------------------------
|
||||
# Runs from the repo root because post-process-specs reads api-docs/.config.yml
|
||||
# paths relative to the api-docs/ directory.
|
||||
|
||||
echo ""
|
||||
echo "========================================"
|
||||
echo "Step 1: Post-processing specs"
|
||||
echo "========================================"
|
||||
cd ..
|
||||
node api-docs/scripts/dist/post-process-specs.js
|
||||
cd api-docs
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Step 2: Generate Redoc HTML
|
||||
# ---------------------------------------------------------------------------
|
||||
# Iterates each product's .config.yml, generates Redoc HTML wrapped in Hugo
|
||||
# frontmatter, and writes to content/{product}/api/_index.html.
|
||||
|
||||
function generateRedocHtml {
|
||||
local specPath="$1"
|
||||
local productVersion="$2"
|
||||
local productDir="$2"
|
||||
local productName="$3"
|
||||
local api="$4"
|
||||
local configPath="$5"
|
||||
|
||||
# Use the product name to define the menu for the Hugo template
|
||||
local menu="$(echo $productVersion | sed 's/\./_/g;s/-/_/g;s/\//_/g;')"
|
||||
# Short version name (for old aliases)
|
||||
# Everything after the last slash
|
||||
local versionDir=$(echo $productVersion | sed 's/.*\///g;')
|
||||
# Extract the API name--for example, "management" from "management@v2".
|
||||
local apiName=$(echo $api | sed 's/@.*//g;')
|
||||
# Extract the API version--for example, "v0" from "management@v0".
|
||||
local apiVersion=$(echo $api | sed 's/.*@//g;')
|
||||
local menu
|
||||
menu="$(echo "$productDir" | sed 's/\./_/g;s/-/_/g;s/\//_/g;')"
|
||||
|
||||
local apiName
|
||||
apiName=$(echo "$api" | sed 's/@.*//g;')
|
||||
|
||||
# Resolve info.yml: try spec directory first, fall back to product directory.
|
||||
local specDir
|
||||
specDir=$(dirname "$specPath")
|
||||
local infoYml=""
|
||||
if [ -f "$specDir/content/info.yml" ]; then
|
||||
infoYml="$specDir/content/info.yml"
|
||||
elif [ -f "$productVersion/content/info.yml" ]; then
|
||||
infoYml="$productVersion/content/info.yml"
|
||||
elif [ -f "$productDir/content/info.yml" ]; then
|
||||
infoYml="$productDir/content/info.yml"
|
||||
fi
|
||||
|
||||
# Use the title and summary defined in the product API's info.yml file.
|
||||
local title=$(yq '.title' "$infoYml")
|
||||
local menuTitle=$(yq '.x-influxdata-short-title' "$infoYml")
|
||||
# Get the shortened description to use for metadata.
|
||||
local shortDescription=$(yq '.x-influxdata-short-description' "$infoYml")
|
||||
# Get the aliases array from the configuration file.
|
||||
local aliases=$(yq e ".apis | .$api | .x-influxdata-docs-aliases" "$configPath")
|
||||
# If aliases is null, set it to an empty YAML array.
|
||||
local title
|
||||
title=$(yq '.title' "$infoYml")
|
||||
local menuTitle
|
||||
menuTitle=$(yq '.x-influxdata-short-title' "$infoYml")
|
||||
local shortDescription
|
||||
shortDescription=$(yq '.x-influxdata-short-description' "$infoYml")
|
||||
|
||||
local aliases
|
||||
aliases=$(yq e ".apis | .$api | .x-influxdata-docs-aliases" "$configPath")
|
||||
if [[ "$aliases" == "null" ]]; then
|
||||
aliases='[]'
|
||||
fi
|
||||
|
||||
local weight=102
|
||||
if [[ $apiName == "v1-compatibility" ]]; then
|
||||
weight=304
|
||||
fi
|
||||
# Define the file name for the Redoc HTML output.
|
||||
|
||||
local specbundle=redoc-static_index.html
|
||||
# Define the temporary file for the Hugo template and Redoc HTML.
|
||||
local tmpfile="${productVersion}-${api}_index.tmp"
|
||||
local tmpfile="${productDir}-${api}_index.tmp"
|
||||
|
||||
echo "Bundling $specPath"
|
||||
|
||||
# Use npx to install and run the specified version of redoc-cli.
|
||||
# npm_config_yes=true npx overrides the prompt
|
||||
# and (vs. npx --yes) is compatible with npm@6 and npm@7.
|
||||
npx --version && \
|
||||
npm_config_yes=true npx redoc-cli@0.12.3 bundle $specPath \
|
||||
--config $configPath \
|
||||
-t template.hbs \
|
||||
--title="$title" \
|
||||
--options.sortPropsAlphabetically \
|
||||
--options.menuToggle \
|
||||
--options.hideHostname \
|
||||
--options.noAutoAuth \
|
||||
--options.hideDownloadButton \
|
||||
--output=$specbundle \
|
||||
--templateOptions.description="$shortDescription" \
|
||||
--templateOptions.product="$productVersion" \
|
||||
--templateOptions.productName="$productName"
|
||||
npm_config_yes=true npx redoc-cli@0.12.3 bundle "$specPath" \
|
||||
--config "$configPath" \
|
||||
-t template.hbs \
|
||||
--title="$title" \
|
||||
--options.sortPropsAlphabetically \
|
||||
--options.menuToggle \
|
||||
--options.hideHostname \
|
||||
--options.noAutoAuth \
|
||||
--options.hideDownloadButton \
|
||||
--output=$specbundle \
|
||||
--templateOptions.description="$shortDescription" \
|
||||
--templateOptions.product="$productDir" \
|
||||
--templateOptions.productName="$productName"
|
||||
|
||||
local frontmatter=$(yq eval -n \
|
||||
".title = \"$title\" |
|
||||
.description = \"$shortDescription\" |
|
||||
.layout = \"api\" |
|
||||
.weight = $weight |
|
||||
.menu.[\"$menu\"].parent = \"InfluxDB HTTP API\" |
|
||||
.menu.[\"$menu\"].name = \"$menuTitle\" |
|
||||
.menu.[\"$menu\"].identifier = \"api-reference-$apiName\" |
|
||||
.aliases = \"$aliases\"")
|
||||
local frontmatter
|
||||
frontmatter=$(yq eval -n \
|
||||
".title = \"$title\" |
|
||||
.description = \"$shortDescription\" |
|
||||
.layout = \"api\" |
|
||||
.weight = $weight |
|
||||
.menu.[\"$menu\"].parent = \"InfluxDB HTTP API\" |
|
||||
.menu.[\"$menu\"].name = \"$menuTitle\" |
|
||||
.menu.[\"$menu\"].identifier = \"api-reference-$apiName\" |
|
||||
.aliases = \"$aliases\"")
|
||||
|
||||
frontmatter="---
|
||||
$frontmatter
|
||||
---
|
||||
"
|
||||
|
||||
# Create the Hugo template file with the frontmatter and Redoc HTML
|
||||
echo "$frontmatter" >> $tmpfile
|
||||
V_LEN_INIT=$(wc -c $tmpfile | awk '{print $1}')
|
||||
cat $specbundle >> $tmpfile
|
||||
V_LEN=$(wc -c $tmpfile | awk '{print $1}')
|
||||
echo "$frontmatter" >> "$tmpfile"
|
||||
V_LEN_INIT=$(wc -c "$tmpfile" | awk '{print $1}')
|
||||
cat $specbundle >> "$tmpfile"
|
||||
V_LEN=$(wc -c "$tmpfile" | awk '{print $1}')
|
||||
|
||||
if ! [[ $V_LEN -gt $V_LEN_INIT ]]
|
||||
then
|
||||
if ! [[ $V_LEN -gt $V_LEN_INIT ]]; then
|
||||
echo "Error: bundle was not appended to $tmpfile"
|
||||
exit $?
|
||||
exit 1
|
||||
fi
|
||||
|
||||
rm -f $specbundle
|
||||
# Create the directory and move the file.
|
||||
if [ ! -z "$apiName" ]; then
|
||||
mkdir -p ../content/$productVersion/api/$apiName
|
||||
mv $tmpfile ../content/$productVersion/api/$apiName/_index.html
|
||||
|
||||
if [ -n "$apiName" ]; then
|
||||
mkdir -p "../content/$productDir/api/$apiName"
|
||||
mv "$tmpfile" "../content/$productDir/api/$apiName/_index.html"
|
||||
else
|
||||
mkdir -p ../content/$productVersion/api
|
||||
mv $tmpfile ../content/$productVersion/api/_index.html
|
||||
mkdir -p "../content/$productDir/api"
|
||||
mv "$tmpfile" "../content/$productDir/api/_index.html"
|
||||
fi
|
||||
}
|
||||
|
||||
# Use a combination of directory names and configuration files to build the API documentation.
|
||||
# Each directory represents a product, and each product directory contains a configuration file that defines APIs and their spec file locations.
|
||||
function build {
|
||||
local versions
|
||||
versions="$(ls -d -- */* | grep -v 'node_modules' | grep -v 'openapi')"
|
||||
for version in $versions; do
|
||||
# Trim the trailing slash off the directory name
|
||||
local version="${version%/}"
|
||||
# Get the version API configuration file.
|
||||
local configPath="$version/.config.yml"
|
||||
if [ ! -f "$configPath" ]; then
|
||||
# Skip to the next version if the configuration file doesn't exist.
|
||||
continue
|
||||
echo ""
|
||||
echo "========================================"
|
||||
echo "Step 2: Generating Redoc HTML"
|
||||
echo "========================================"
|
||||
|
||||
# Iterate product directories that contain a .config.yml.
|
||||
for configPath in $(find . -name '.config.yml' -not -path '*/node_modules/*' -not -path '*/openapi/*'); do
|
||||
productDir=$(dirname "$configPath")
|
||||
# Strip leading ./
|
||||
productDir="${productDir#./}"
|
||||
configPath="${configPath#./}"
|
||||
|
||||
echo "Using config $productDir $configPath"
|
||||
|
||||
local_product_name=$(yq e '.x-influxdata-product-name' "$configPath")
|
||||
if [[ -z "$local_product_name" ]]; then
|
||||
local_product_name=InfluxDB
|
||||
fi
|
||||
|
||||
apis=$(yq e '.apis | keys | .[]' "$configPath")
|
||||
|
||||
while IFS= read -r api; do
|
||||
echo "======Building $productDir $api======"
|
||||
|
||||
specRootPath=$(yq e ".apis | .$api | .root" "$configPath")
|
||||
specPath="$productDir/$specRootPath"
|
||||
|
||||
if [ -d "$specPath" ] || [ ! -f "$specPath" ]; then
|
||||
echo "OpenAPI spec $specPath doesn't exist. Skipping."
|
||||
continue
|
||||
fi
|
||||
echo "Using config $version $configPath"
|
||||
# Get the product name from the configuration.
|
||||
local versionName
|
||||
versionName=$(yq e '.x-influxdata-product-name' "$configPath")
|
||||
if [[ -z "$versionName" ]]; then
|
||||
versionName=InfluxDB
|
||||
|
||||
# If -c flag set, only regenerate specs that differ from master.
|
||||
update=0
|
||||
if [[ $generate_changed == 0 ]]; then
|
||||
diff_result=$(git diff --name-status master -- "${specPath}" 2>/dev/null || true)
|
||||
if [[ -z "$diff_result" ]]; then
|
||||
update=1
|
||||
fi
|
||||
fi
|
||||
# Get an array of API names (keys) from the configuration file
|
||||
local apis
|
||||
apis=$(yq e '.apis | keys | .[]' "$configPath")
|
||||
# Read each element of the apis array
|
||||
while IFS= read -r api; do
|
||||
echo "======Building $version $api======"
|
||||
# Get the spec file path from the configuration.
|
||||
local specRootPath
|
||||
specRootPath=$(yq e ".apis | .$api | .root" "$configPath")
|
||||
# Check that the YAML spec file exists.
|
||||
local specPath
|
||||
specPath="$version/$specRootPath"
|
||||
if [ -d "$specPath" ] || [ ! -f "$specPath" ]; then
|
||||
echo "OpenAPI spec $specPath doesn't exist."
|
||||
fi
|
||||
|
||||
if [[ $update -eq 0 ]]; then
|
||||
echo "Regenerating $productDir $api"
|
||||
generateRedocHtml "$specPath" "$productDir" "$local_product_name" "$api" "$configPath"
|
||||
fi
|
||||
|
||||
# If the spec file differs from master, regenerate the HTML.
|
||||
local update=0
|
||||
if [[ $generate_changed == 0 ]]; then
|
||||
local diff
|
||||
diff=$(git diff --name-status master -- "${specPath}")
|
||||
if [[ -z "$diff" ]]; then
|
||||
update=1
|
||||
fi
|
||||
fi
|
||||
echo -e "========Finished $productDir $api========\n\n"
|
||||
done <<< "$apis"
|
||||
done
|
||||
|
||||
if [[ $update -eq 0 ]]; then
|
||||
echo "Regenerating $version $api"
|
||||
generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath"
|
||||
fi
|
||||
echo -e "========Finished $version $api========\n\n"
|
||||
done <<< "$apis"
|
||||
done
|
||||
}
|
||||
# ---------------------------------------------------------------------------
|
||||
# Step 3: Copy specs to static/openapi/ for download
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
build
|
||||
|
||||
# Apply content overlays (info, servers) and tag configs to bundled specs
|
||||
echo "Post-processing specs..."
|
||||
echo ""
|
||||
echo "========================================"
|
||||
echo "Step 3: Copying specs to static/openapi/"
|
||||
echo "========================================"
|
||||
cd ..
|
||||
node api-docs/scripts/dist/post-process-specs.js
|
||||
node api-docs/scripts/dist/generate-openapi-articles.js --static-only
|
||||
cd api-docs
|
||||
|
||||
# Generate tag-based article data, content pages, and static spec downloads
|
||||
echo "Generating OpenAPI article data..."
|
||||
cd ..
|
||||
node api-docs/scripts/dist/generate-openapi-articles.js
|
||||
cd api-docs
|
||||
echo ""
|
||||
echo "========================================"
|
||||
echo "Done"
|
||||
echo "========================================"
|
||||
|
|
|
|||
|
|
@ -217,7 +217,7 @@ function updateClusteredV2 {
|
|||
}
|
||||
|
||||
function updateCoreV3 {
|
||||
outFile="influxdb3/core/v3/influxdb3-core-openapi.yaml"
|
||||
outFile="influxdb3/core/influxdb3-core-openapi.yaml"
|
||||
if [[ -z "$baseUrl" ]];
|
||||
then
|
||||
echo "Using existing $outFile"
|
||||
|
|
@ -229,7 +229,7 @@ function updateCoreV3 {
|
|||
}
|
||||
|
||||
function updateEnterpriseV3 {
|
||||
outFile="influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml"
|
||||
outFile="influxdb3/enterprise/influxdb3-enterprise-openapi.yaml"
|
||||
if [[ -z "$baseUrl" ]];
|
||||
then
|
||||
echo "Using existing $outFile"
|
||||
|
|
|
|||
|
|
@ -15,6 +15,8 @@ info:
|
|||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
x-influxdata-short-title: v2 API
|
||||
x-influxdata-short-description: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with InfluxDB v2.
|
||||
servers:
|
||||
- url: https://{baseurl}
|
||||
description: InfluxDB Cloud API URL
|
||||
|
|
@ -27,325 +29,130 @@ servers:
|
|||
security:
|
||||
- TokenAuthentication: []
|
||||
tags:
|
||||
- description: |
|
||||
Use one of the following schemes to authenticate to the InfluxDB API:
|
||||
|
||||
- [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
- description: Authenticate API requests to InfluxDB Cloud using API tokens with token, basic, or querystring authentication schemes.
|
||||
name: Authentication
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Create and manage authorizations (API tokens).
|
||||
|
||||
An _authorization_ contains a list of `read` and `write`
|
||||
permissions for organization resources and provides an API token for authentication.
|
||||
An authorization belongs to an organization and only contains permissions for that organization.
|
||||
|
||||
We recommend the following for managing your tokens:
|
||||
|
||||
- Create a generic user to create and manage tokens for writing data.
|
||||
- Store your tokens in a secure password vault for future access.
|
||||
|
||||
### User sessions with authorizations
|
||||
|
||||
Optionally, when creating an authorization, you can scope it to a specific user.
|
||||
If the user signs in with username and password, creating a _user session_,
|
||||
the session carries the permissions granted by all the user's authorizations.
|
||||
For more information, see [how to assign a token to a specific user](/influxdb/cloud/security/tokens/create-token/).
|
||||
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
|
||||
|
||||
### Related endpoints
|
||||
|
||||
- [Signin](#tag/Signin)
|
||||
- [Signout](#tag/Signout)
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication)
|
||||
- [Manage API tokens](/influxdb/cloud/security/tokens/)
|
||||
- [Assign a token to a specific user](/influxdb/cloud/security/tokens/create-token/)
|
||||
- description: Create and manage API token authorizations that grant read and write permissions to InfluxDB Cloud organization resources.
|
||||
name: Authorizations (API tokens)
|
||||
x-related:
|
||||
- title: Manage API tokens
|
||||
href: /influxdb/cloud/security/tokens/
|
||||
- name: Bucket Schemas
|
||||
- description: |
|
||||
Store your data in InfluxDB [buckets](/influxdb/cloud/reference/glossary/#bucket).
|
||||
A bucket is a named location where time series data is stored. All buckets
|
||||
have a [retention period](/influxdb/cloud/reference/glossary/#retention-period),
|
||||
a duration of time that each data point persists. InfluxDB drops all
|
||||
points with timestamps older than the bucket’s retention period.
|
||||
A bucket belongs to an organization.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Manage buckets](/influxdb/cloud/organizations/buckets/)
|
||||
description: Manage explicit schemas for InfluxDB Cloud buckets to enforce column names and data types for measurement data.
|
||||
- description: Create and manage named storage locations (buckets) in InfluxDB Cloud, each with a configurable retention period.
|
||||
name: Buckets
|
||||
x-related:
|
||||
- title: Manage buckets
|
||||
href: /influxdb/cloud/organizations/buckets/
|
||||
- name: Cells
|
||||
description: Manage cells within InfluxDB Cloud dashboards.
|
||||
- name: Checks
|
||||
- description: |
|
||||
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).
|
||||
|
||||
### Common parameters
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/cloud/organizations/buckets/view-buckets/). |
|
||||
| `bucketID` | string | The bucket ID ([find your bucket](/influxdb/cloud/organizations/buckets/view-buckets/). |
|
||||
| `org` | string | The organization name or ID ([find your organization](/influxdb/cloud/organizations/view-orgs/). |
|
||||
| `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/cloud/organizations/view-orgs/). |
|
||||
description: Create and manage monitoring checks that query data on a schedule and generate notification statuses in InfluxDB Cloud.
|
||||
- description: Common query parameters used by InfluxDB Cloud API endpoints, including `bucket`, `bucketID`, `org`, and `orgID`.
|
||||
name: Common parameters
|
||||
x-traitTag: true
|
||||
- name: Config
|
||||
description: Retrieve configuration information for an InfluxDB Cloud instance.
|
||||
- name: Dashboards
|
||||
- description: |
|
||||
The InfluxDB 1.x data model includes [databases](/influxdb/cloud/reference/glossary/#database)
|
||||
and [retention policies](/influxdb/cloud/reference/glossary/#retention-policy-rp).
|
||||
InfluxDB 2.x replaces databases and retention policies with buckets.
|
||||
To support InfluxDB 1.x query and write patterns in InfluxDB 2.x,
|
||||
databases and retention policies are mapped to buckets using the
|
||||
database and retention policy (DBRP) mapping service.
|
||||
The DBRP mapping service uses the database and retention policy
|
||||
specified in 1.x compatibility API requests to route operations to a bucket.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/)
|
||||
description: Create and manage dashboards in InfluxDB Cloud.
|
||||
- description: Manage database and retention policy (DBRP) mappings that route InfluxDB v1-compatible requests to InfluxDB Cloud buckets.
|
||||
name: DBRPs
|
||||
- description: |
|
||||
Delete data from an InfluxDB bucket.
|
||||
x-related:
|
||||
- title: Database and retention policy mapping
|
||||
href: /influxdb/cloud/reference/api/influxdb-1x/dbrp/
|
||||
- description: Delete time series data from an InfluxDB Cloud bucket by specifying a time range and optional tag predicate.
|
||||
name: Delete
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
||||
the `POST /api/v2/write` endpoint accepts the `Content-Encoding` header to indicate the compression applied to line protocol in the request body.
|
||||
|
||||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `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. |
|
||||
- description: Standard HTTP request headers used by InfluxDB Cloud API endpoints, including `Accept`, `Authorization`, `Content-Length`, and `Content-Type`.
|
||||
name: Headers
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Store, manage, and execute scripts in InfluxDB.
|
||||
A script stores your custom Flux script and provides an invokable
|
||||
endpoint that accepts runtime parameters.
|
||||
In a script, you can specify custom runtime parameters
|
||||
(`params`)--for example, `params.myparameter`.
|
||||
Once you create a script, InfluxDB generates an
|
||||
[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)
|
||||
for your organization.
|
||||
You can run the script from API requests and tasks, defining parameter
|
||||
values for each run.
|
||||
When the script runs, InfluxDB replaces `params` references in the
|
||||
script with the runtime parameter values you define.
|
||||
|
||||
Use the `/api/v2/scripts` endpoints to create and manage scripts.
|
||||
See related guides to learn how to define parameters and execute scripts.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) from API requests.
|
||||
- [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)
|
||||
- description: Store, manage, and execute custom Flux scripts in InfluxDB Cloud. Scripts accept runtime parameters and can be invoked via dedicated endpoints.
|
||||
name: Invokable Scripts
|
||||
- name: Labels
|
||||
description: Create and manage labels for organizing InfluxDB Cloud resources such as dashboards, tasks, and buckets.
|
||||
- name: Legacy Authorizations
|
||||
description: Manage legacy (v1-compatible) authorization credentials in InfluxDB Cloud.
|
||||
- name: Legacy Query
|
||||
description: Query data using InfluxQL via the v1-compatible `/query` endpoint in InfluxDB Cloud.
|
||||
- name: Legacy Write
|
||||
description: Write data using the v1-compatible `/write` endpoint in InfluxDB Cloud.
|
||||
- name: Limits
|
||||
description: Retrieve rate limits and usage quotas for an InfluxDB Cloud organization.
|
||||
- name: NotificationEndpoints
|
||||
description: Create and manage notification endpoints that receive alert notifications from InfluxDB Cloud monitoring checks.
|
||||
- name: NotificationRules
|
||||
- description: |
|
||||
Manage your [organization](/influxdb/cloud/reference/glossary/#organization).
|
||||
An organization is a workspace for a group of users. Organizations can be
|
||||
used to separate different environments, projects, teams or users within
|
||||
InfluxDB.
|
||||
|
||||
Use the `/api/v2/orgs` endpoints to view and manage organizations.
|
||||
description: Create and manage notification rules that define when and how InfluxDB Cloud sends notifications to configured endpoints.
|
||||
- description: View and manage InfluxDB Cloud organizations, which are workspaces that group users, buckets, and resources.
|
||||
name: Organizations
|
||||
- description: |
|
||||
Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `limit` | integer | The maximum number of records to return (after other parameters are applied). |
|
||||
| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |
|
||||
| `after` | string (resource ID) | Only returns resources created after the specified resource. |
|
||||
|
||||
### Limitations
|
||||
|
||||
- For specific endpoint parameters and examples, see the endpoint definition.
|
||||
- If you specify an `offset` parameter value greater than the total number of records,
|
||||
then InfluxDB returns an empty list in the response
|
||||
(given `offset` skips the specified number of records).
|
||||
|
||||
The following example passes `offset=50` to skip the first 50 results,
|
||||
but the user only has 10 buckets:
|
||||
|
||||
```sh
|
||||
curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" \
|
||||
--header "Authorization: Token INFLUX_API_TOKEN"
|
||||
```
|
||||
|
||||
The response contains the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"links": {
|
||||
"prev": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=49\u0026orgID=ORG_ID",
|
||||
"self": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=50\u0026orgID=ORG_ID"
|
||||
},
|
||||
"buckets": []
|
||||
}
|
||||
```
|
||||
x-related:
|
||||
- title: View and manage organizations
|
||||
href: /influxdb/cloud/organizations/
|
||||
- description: Query parameters for paginating results from list operations in the InfluxDB Cloud API.
|
||||
name: Pagination
|
||||
x-traitTag: true
|
||||
- name: Ping
|
||||
- description: |
|
||||
Retrieve data, analyze queries, and get query suggestions.
|
||||
description: Check the availability of the InfluxDB Cloud instance.
|
||||
- description: Retrieve data, analyze queries, and get query suggestions using the InfluxDB Cloud query API.
|
||||
name: Query data
|
||||
- description: |
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
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.
|
||||
x-related:
|
||||
- title: Query data
|
||||
href: /influxdb/cloud/query-data/
|
||||
- description: Get started authenticating, writing, and querying data with the InfluxDB Cloud API.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- name: Resources
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP status codes for success and failure responses.
|
||||
The response body may include additional details.
|
||||
For details about a specific operation's response,
|
||||
see **Responses** and **Response Samples** for that operation.
|
||||
|
||||
API operations may return the following HTTP status codes:
|
||||
|
||||
| Code | Status | Description |
|
||||
|:-----------:|:------------------------ |:--------------------- |
|
||||
| `200` | Success | |
|
||||
| `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. |
|
||||
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: <ul><li>Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the `rejected_points` measurement in your [_monitoring bucket](/influxdb/cloud/reference/internals/system-buckets/#_monitoring-system-bucket).</li><li>`Authorization` header is missing or malformed or the API token doesn't have permission for the operation.</li></ul> |
|
||||
| `401` | Unauthorized | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb/cloud/security/tokens/)</li></ul> |
|
||||
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
|
||||
| `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. |
|
||||
| `413` | Request entity too large | Request payload exceeds the size limit. |
|
||||
| `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
|
||||
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
|
||||
| `500` | Internal server error | |
|
||||
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
|
||||
description: Retrieve a list of top-level resource types available in the InfluxDB Cloud API.
|
||||
- description: Standard HTTP status codes returned by InfluxDB Cloud API endpoints and their meanings.
|
||||
name: Response codes
|
||||
x-traitTag: true
|
||||
- name: Routes
|
||||
description: Retrieve top-level routes for the InfluxDB Cloud API.
|
||||
- name: Rules
|
||||
description: Manage notification rules in InfluxDB Cloud.
|
||||
- name: Secrets
|
||||
description: Create and manage secrets (key-value pairs) for use in InfluxDB Cloud Flux scripts and tasks.
|
||||
- name: Security and access endpoints
|
||||
description: Endpoints for managing authentication and access control in InfluxDB Cloud.
|
||||
- name: Setup
|
||||
description: Configure an initial InfluxDB Cloud instance, including creating the initial user, organization, and bucket.
|
||||
- name: Signin
|
||||
description: Create a user session by signing in with username and password credentials.
|
||||
- name: Signout
|
||||
- description: "The following table shows the most common operations that the InfluxDB `/api/v2` API supports.\nSome resources may support other operations that perform functions more specific to those resources.\nFor example, you can use the `PATCH /api/v2/scripts` endpoint to update properties of a script\nresource.\n\n| Operation | |\n|:----------|:-----------------------------------------------------------------------|\n| Write | Writes (`POST`) data to a bucket. |\n| Run | Executes (`POST`) a query or script and returns the result. |\n| List |\tRetrieves (`GET`) a list of zero or more resources. |\n| Create |\tCreates (`POST`) a new resource and returns the resource. |\n| Update |\tModifies (`PUT`) an existing resource to reflect data in your request. |\n| Delete |\tRemoves (`DELETE`) a specific resource. |\n"
|
||||
description: End a user session by signing out.
|
||||
- description: Overview of the common CRUD operations supported by the InfluxDB Cloud API.
|
||||
name: Supported operations
|
||||
x-traitTag: true
|
||||
- name: System information endpoints
|
||||
- description: |
|
||||
Process and analyze your data with [tasks](/influxdb/cloud/reference/glossary/#task)
|
||||
in the InfluxDB task engine.
|
||||
Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.
|
||||
|
||||
To configure a task, provide the script and the schedule to run the task.
|
||||
For examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).
|
||||
|
||||
<span id="tasks-schemaref-task" />
|
||||
|
||||
### Properties
|
||||
|
||||
A `task` object contains information about an InfluxDB task resource.
|
||||
|
||||
The following table defines the properties that appear in this object:
|
||||
|
||||
<SchemaDefinition schemaRef="#/components/schemas/Task" />
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Get started with tasks](/influxdb/cloud/process-data/get-started/)
|
||||
- [Common data processing tasks](/influxdb/cloud/process-data/common-tasks/)
|
||||
- [Create a script](/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script)
|
||||
description: Endpoints for retrieving system-level information about the InfluxDB Cloud instance.
|
||||
- description: Schedule and manage Flux tasks that process and transform data on a recurring basis in InfluxDB Cloud.
|
||||
name: Tasks
|
||||
x-related:
|
||||
- title: Get started with tasks
|
||||
href: /influxdb/cloud/process-data/get-started/
|
||||
- name: Telegraf Plugins
|
||||
description: Retrieve available Telegraf plugin configuration templates for use with InfluxDB Cloud.
|
||||
- name: Telegrafs
|
||||
- description: |
|
||||
Export and apply InfluxDB **templates**.
|
||||
Manage **stacks** of templated InfluxDB resources.
|
||||
|
||||
InfluxDB templates are prepackaged configurations for resources.
|
||||
Use InfluxDB templates to configure a fresh instance of InfluxDB,
|
||||
back up your dashboard configuration, or share your configuration.
|
||||
|
||||
Use the `/api/v2/templates` endpoints to export templates and apply templates.
|
||||
|
||||
**InfluxDB stacks** are stateful InfluxDB templates that let you
|
||||
add, update, and remove installed template resources over time, avoid duplicating
|
||||
resources when applying the same or similar templates more than once, and
|
||||
apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.
|
||||
|
||||
Use the `/api/v2/stacks` endpoints to manage installed template resources.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/)
|
||||
- [InfluxDB templates](/influxdb/cloud/influxdb-templates/)
|
||||
description: Create and manage Telegraf agent configurations that collect and write data to InfluxDB Cloud.
|
||||
- description: Export and apply InfluxDB templates, and manage template stacks for InfluxDB Cloud.
|
||||
name: Templates
|
||||
x-related:
|
||||
- title: InfluxDB templates
|
||||
href: /influxdb/cloud/influxdb-templates/
|
||||
- name: Usage
|
||||
- description: |
|
||||
Retrieve specific users.
|
||||
|
||||
InfluxDB Cloud lets you invite and collaborate with multiple users in your organization.
|
||||
To invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);
|
||||
you can't use the InfluxDB API to manage users in InfluxDB Cloud.
|
||||
Once a user is added to your organization, you can use the
|
||||
`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to
|
||||
view specific members.
|
||||
|
||||
### User sessions with authorizations
|
||||
|
||||
Optionally, you can scope an authorization (and its API token) to a user.
|
||||
If a user signs in with username and password, creating a _user session_,
|
||||
the session carries the permissions granted by all the user's authorizations.
|
||||
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Manage users](/influxdb/cloud/organizations/users/)
|
||||
description: Retrieve usage metrics and cardinality data for an InfluxDB Cloud organization.
|
||||
- description: View specific users that are members of your InfluxDB Cloud organization.
|
||||
name: Users
|
||||
x-related:
|
||||
- title: Manage users
|
||||
href: /influxdb/cloud/organizations/users/
|
||||
- name: Variables
|
||||
description: Create and manage variables for use in InfluxDB Cloud dashboards.
|
||||
- name: Views
|
||||
- description: |
|
||||
Write time series data to [buckets](/influxdb/cloud/reference/glossary/#bucket).
|
||||
description: Manage cell views within InfluxDB Cloud dashboards.
|
||||
- description: Write time series data to InfluxDB Cloud buckets in line protocol format using the `/api/v2/write` endpoint.
|
||||
name: Write data
|
||||
x-related:
|
||||
- title: Write data
|
||||
href: /influxdb/cloud/write-data/
|
||||
paths:
|
||||
/api/v2:
|
||||
get:
|
||||
|
|
|
|||
|
|
@ -28,6 +28,8 @@ info:
|
|||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
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.
|
||||
servers:
|
||||
- url: http://localhost:8086
|
||||
description: Local InfluxDB instance
|
||||
|
|
@ -36,47 +38,18 @@ security:
|
|||
- QueryAuth: []
|
||||
tags:
|
||||
- name: System Information
|
||||
description: |
|
||||
Endpoints for checking server status, health, and version information.
|
||||
description: Check server status, health, and version information for an InfluxDB v1 instance.
|
||||
- name: Query
|
||||
description: |
|
||||
Query data using InfluxQL. The `/query` endpoint supports both read queries
|
||||
(SELECT, SHOW) and write queries (CREATE, DROP, ALTER, etc.).
|
||||
description: Query data using InfluxQL via the `/query` endpoint, supporting both read queries (SELECT, SHOW) and management queries (CREATE, DROP, ALTER).
|
||||
- name: Write
|
||||
description: |
|
||||
Write time series data using InfluxDB line protocol.
|
||||
description: Write time series data to InfluxDB v1 in line protocol format using the `/write` endpoint.
|
||||
- name: Debug
|
||||
description: |
|
||||
Debugging and profiling endpoints for troubleshooting and performance analysis.
|
||||
description: Access debugging and profiling endpoints for troubleshooting and performance analysis of an InfluxDB v1 instance.
|
||||
- name: v2 Compatibility
|
||||
description: |
|
||||
InfluxDB 2.x API compatibility endpoints. These endpoints allow you to use
|
||||
InfluxDB 2.x client libraries with InfluxDB 1.8+.
|
||||
|
||||
Use the `Token` scheme with v1.x credentials:
|
||||
```
|
||||
Authorization: Token username:password
|
||||
```
|
||||
description: InfluxDB v2-compatible API endpoints that allow InfluxDB 2.x client libraries to work with InfluxDB 1.8+, using the Token authentication scheme with v1 credentials.
|
||||
- name: Authentication
|
||||
x-traitTag: true
|
||||
description: |
|
||||
InfluxDB 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
|
||||
```
|
||||
description: Authenticate API requests to InfluxDB v1 using basic authentication, query string credentials, or the v2-compatible token scheme.
|
||||
paths:
|
||||
/ping:
|
||||
get:
|
||||
|
|
|
|||
|
|
@ -16,336 +16,153 @@ info:
|
|||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
x-influxdata-short-title: v2 API
|
||||
servers:
|
||||
- url: /
|
||||
security:
|
||||
- TokenAuthentication: []
|
||||
tags:
|
||||
- description: |
|
||||
Use one of the following schemes to authenticate to the InfluxDB API:
|
||||
|
||||
- [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
- description: Authenticate API requests to InfluxDB OSS v2 using API tokens with token, basic, or querystring authentication schemes.
|
||||
name: Authentication
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Create and manage authorizations (API tokens).
|
||||
|
||||
An _authorization_ contains a list of `read` and `write`
|
||||
permissions for organization resources and provides an API token for authentication.
|
||||
An authorization belongs to an organization and only contains permissions for that organization.
|
||||
|
||||
We recommend creating a generic user to create and manage tokens for writing data.
|
||||
|
||||
### User sessions with authorizations
|
||||
|
||||
Optionally, when creating an authorization, you can scope it to a specific user.
|
||||
If a user signs in with username and password, creating a _user session_,
|
||||
the session carries the permissions granted by all the user's authorizations.
|
||||
For more information, see [how to assign a token to a specific user](/influxdb/v2/security/tokens/create-token/).
|
||||
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
|
||||
|
||||
### Related endpoints
|
||||
|
||||
- [Signin](#tag/Signin)
|
||||
- [Signout](#tag/Signout)
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Authorize API requests](/influxdb/v2/api-guide/api_intro/#authentication)
|
||||
- [Manage API tokens](/influxdb/v2/security/tokens/)
|
||||
- [Assign a token to a specific user](/influxdb/v2/security/tokens/create-token/)
|
||||
- description: Create and manage API token authorizations that grant read and write permissions to InfluxDB OSS v2 organization resources.
|
||||
name: Authorizations (API tokens)
|
||||
x-related:
|
||||
- title: Manage API tokens
|
||||
href: /influxdb/v2/security/tokens/
|
||||
- name: Authorizations (v1-compatible)
|
||||
description: Manage v1-compatible legacy authorization credentials in InfluxDB OSS v2.
|
||||
- name: Backup
|
||||
- description: |
|
||||
Store your data in InfluxDB [buckets](/influxdb/v2/reference/glossary/#bucket).
|
||||
A bucket is a named location where time series data is stored. All buckets
|
||||
have a [retention period](/influxdb/v2/reference/glossary/#retention-period),
|
||||
a duration of time that each data point persists. InfluxDB drops all
|
||||
points with timestamps older than the bucket’s retention period.
|
||||
A bucket belongs to an organization.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Manage buckets](/influxdb/v2/organizations/buckets/)
|
||||
description: Back up InfluxDB OSS v2 data, including time series data and metadata, for use in restore operations.
|
||||
- description: Create and manage named storage locations (buckets) in InfluxDB OSS v2, each with a configurable retention period.
|
||||
name: Buckets
|
||||
x-related:
|
||||
- title: Manage buckets
|
||||
href: /influxdb/v2/organizations/buckets/
|
||||
- name: Cells
|
||||
description: Manage cells within InfluxDB OSS v2 dashboards.
|
||||
- name: Checks
|
||||
- description: |
|
||||
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).
|
||||
|
||||
### Common parameters
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/v2/organizations/buckets/view-buckets/). |
|
||||
| `bucketID` | string | The bucket ID ([find your bucket](/influxdb/v2/organizations/buckets/view-buckets/). |
|
||||
| `org` | string | The organization name or ID ([find your organization](/influxdb/v2/organizations/view-orgs/). |
|
||||
| `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/v2/organizations/view-orgs/). |
|
||||
description: Create and manage monitoring checks that query data on a schedule and generate notification statuses in InfluxDB OSS v2.
|
||||
- description: Common query parameters used by InfluxDB OSS v2 API endpoints, including `bucket`, `bucketID`, `org`, and `orgID`.
|
||||
name: Common parameters
|
||||
x-traitTag: true
|
||||
- name: Compatibility endpoints
|
||||
description: |
|
||||
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.
|
||||
description: InfluxDB v1-compatible API endpoints for backward compatibility with InfluxDB 1.x clients, tools, and integrations such as Grafana and Telegraf.
|
||||
- name: Config
|
||||
description: Retrieve configuration information for an InfluxDB OSS v2 instance.
|
||||
- name: Dashboards
|
||||
- description: |
|
||||
The InfluxDB 1.x data model includes [databases](/influxdb/v2/reference/glossary/#database)
|
||||
and [retention policies](/influxdb/v2/reference/glossary/#retention-policy-rp).
|
||||
InfluxDB 2.x replaces databases and retention policies with buckets.
|
||||
To support InfluxDB 1.x query and write patterns in InfluxDB 2.x,
|
||||
databases and retention policies are mapped to buckets using the
|
||||
database and retention policy (DBRP) mapping service.
|
||||
The DBRP mapping service uses the database and retention policy
|
||||
specified in v1 compatibility API requests to route operations to a bucket.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Database and retention policy mapping](/influxdb/v2/reference/api/influxdb-1x/dbrp/)
|
||||
description: Create and manage dashboards in InfluxDB OSS v2.
|
||||
- description: Manage database and retention policy (DBRP) mappings that route InfluxDB v1-compatible requests to InfluxDB OSS v2 buckets.
|
||||
name: DBRPs
|
||||
- description: |
|
||||
Generate profiling and trace reports.
|
||||
|
||||
Use routes under `/debug/pprof` to analyze the Go runtime of InfluxDB.
|
||||
These endpoints generate [Go runtime profiles](https://pkg.go.dev/runtime/pprof)
|
||||
and **trace** reports.
|
||||
**Profiles** are collections of stack traces that show call sequences
|
||||
leading to instances of a particular event, such as allocation.
|
||||
|
||||
For more information about **pprof profile** and **trace** reports,
|
||||
see the following resources:
|
||||
|
||||
- [Google pprof tool](https://github.com/google/pprof)
|
||||
- [Golang diagnostics](https://go.dev/doc/diagnostics)
|
||||
x-related:
|
||||
- title: Database and retention policy mapping
|
||||
href: /influxdb/v2/reference/api/influxdb-1x/dbrp/
|
||||
- description: Generate Go runtime profiling and trace reports for troubleshooting and performance analysis of an InfluxDB OSS v2 instance.
|
||||
name: Debug
|
||||
- description: |
|
||||
Delete data from an InfluxDB bucket.
|
||||
- description: Delete time series data from an InfluxDB OSS v2 bucket by specifying a time range and optional tag predicate.
|
||||
name: Delete
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
||||
the `POST /api/v2/write` endpoint accepts the `Content-Encoding` header to indicate the compression applied to line protocol in the request body.
|
||||
|
||||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `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. |
|
||||
- description: Standard HTTP request headers used by InfluxDB OSS v2 API endpoints, including `Accept`, `Authorization`, `Content-Length`, and `Content-Type`.
|
||||
name: Headers
|
||||
x-traitTag: true
|
||||
- name: Health
|
||||
description: Check the health and readiness of an InfluxDB OSS v2 instance.
|
||||
- name: Labels
|
||||
description: Create and manage labels for organizing InfluxDB OSS v2 resources such as dashboards, tasks, and buckets.
|
||||
- name: Metrics
|
||||
description: Retrieve internal metrics for an InfluxDB OSS v2 instance in Prometheus exposition format.
|
||||
- name: NotificationEndpoints
|
||||
description: Create and manage notification endpoints that receive alert notifications from InfluxDB OSS v2 monitoring checks.
|
||||
- name: NotificationRules
|
||||
- description: |
|
||||
Create and manage your [organizations](/influxdb/v2/reference/glossary/#organization).
|
||||
An organization is a workspace for a group of users. Organizations can be
|
||||
used to separate different environments, projects, teams or users within
|
||||
InfluxDB.
|
||||
|
||||
Use the `/api/v2/orgs` endpoints to create, view, and manage organizations.
|
||||
description: Create and manage notification rules that define when and how InfluxDB OSS v2 sends notifications to configured endpoints.
|
||||
- description: Create and manage InfluxDB OSS v2 organizations, which are workspaces that group users, buckets, and resources.
|
||||
name: Organizations
|
||||
- description: |
|
||||
Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `limit` | integer | The maximum number of records to return (after other parameters are applied). |
|
||||
| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |
|
||||
| `after` | string (resource ID) | Only returns resources created after the specified resource. |
|
||||
|
||||
### Limitations
|
||||
|
||||
- For specific endpoint parameters and examples, see the endpoint definition.
|
||||
- If you specify an `offset` parameter value greater than the total number of records,
|
||||
then InfluxDB returns an empty list in the response
|
||||
(given `offset` skips the specified number of records).
|
||||
|
||||
The following example passes `offset=50` to skip the first 50 results,
|
||||
but the user only has 10 buckets:
|
||||
|
||||
```sh
|
||||
curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" \
|
||||
--header "Authorization: Token INFLUX_API_TOKEN"
|
||||
```
|
||||
|
||||
The response contains the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"links": {
|
||||
"prev": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=49\u0026orgID=ORG_ID",
|
||||
"self": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=50\u0026orgID=ORG_ID"
|
||||
},
|
||||
"buckets": []
|
||||
}
|
||||
```
|
||||
x-related:
|
||||
- title: Manage organizations
|
||||
href: /influxdb/v2/organizations/
|
||||
- description: Query parameters for paginating results from list operations in the InfluxDB OSS v2 API.
|
||||
name: Pagination
|
||||
x-traitTag: true
|
||||
- name: Ping
|
||||
- description: |
|
||||
Retrieve data, analyze queries, and get query suggestions.
|
||||
description: Check the availability of an InfluxDB OSS v2 instance.
|
||||
- description: Retrieve data, analyze queries, and get query suggestions using the InfluxDB OSS v2 query API.
|
||||
name: Query data
|
||||
x-related:
|
||||
- title: Query data
|
||||
href: /influxdb/v2/query-data/
|
||||
- name: Query data (v1-compatible)
|
||||
- description: |
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
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.
|
||||
description: Query data in InfluxDB OSS v2 using InfluxQL via the v1-compatible `/query` endpoint.
|
||||
- description: Get started authenticating, writing, and querying data with the InfluxDB OSS v2 API.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- name: Ready
|
||||
description: Check whether an InfluxDB OSS v2 instance is ready to accept requests.
|
||||
- name: RemoteConnections
|
||||
description: Create and manage remote InfluxDB connections for replicating data from an InfluxDB OSS v2 instance to a remote InfluxDB instance.
|
||||
- name: Replications
|
||||
description: Create and manage replication streams that copy data from an InfluxDB OSS v2 bucket to a remote InfluxDB instance.
|
||||
- name: Resources
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP status codes for success and failure responses.
|
||||
The response body may include additional details.
|
||||
For details about a specific operation's response,
|
||||
see **Responses** and **Response Samples** for that operation.
|
||||
|
||||
API operations may return the following HTTP status codes:
|
||||
|
||||
| Code | Status | Description |
|
||||
|:-----------:|:------------------------ |:--------------------- |
|
||||
| `200` | Success | |
|
||||
| `204` | Success. No content | InfluxDB doesn't return data for the request. |
|
||||
| `400` | Bad request | May indicate one of the following:<ul><li>the request body is malformed</li><li>`Authorization` header is missing or malformed</li><li>the API token doesn't have permission for the operation.</li></ul> |
|
||||
| `401` | Unauthorized | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb/v2/security/tokens/)</li></ul> |
|
||||
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
|
||||
| `413` | Request entity too large | Request payload exceeds the size limit. |
|
||||
| `422` | Unprocessable entity | Request data is invalid. The request was well-formed, but couldn't complete due to semantic errors--for example, some or all points in a write request were rejected due to a schema or retention policy violation. The response body provides details about the problem. For more information about rejected points, see how to [Troubleshoot issues writing data](/influxdb/v2/write-data/troubleshoot/)|
|
||||
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
|
||||
| `500` | Internal server error | |
|
||||
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
|
||||
description: Retrieve a list of top-level resource types available in the InfluxDB OSS v2 API.
|
||||
- description: Standard HTTP status codes returned by InfluxDB OSS v2 API endpoints and their meanings.
|
||||
name: Response codes
|
||||
x-traitTag: true
|
||||
- name: Restore
|
||||
description: Restore InfluxDB OSS v2 data from a backup, including time series data and metadata.
|
||||
- name: Routes
|
||||
description: Retrieve top-level routes for the InfluxDB OSS v2 API.
|
||||
- name: Rules
|
||||
description: Manage notification rules in InfluxDB OSS v2.
|
||||
- name: Scraper Targets
|
||||
description: Create and manage Prometheus scraper targets that collect metrics and write them to InfluxDB OSS v2 buckets.
|
||||
- name: Secrets
|
||||
description: Create and manage secrets (key-value pairs) for use in InfluxDB OSS v2 Flux scripts and tasks.
|
||||
- name: Security and access endpoints
|
||||
description: Endpoints for managing authentication and access control in InfluxDB OSS v2.
|
||||
- name: Setup
|
||||
description: Configure a new InfluxDB OSS v2 instance, including creating the initial user, organization, bucket, and API token.
|
||||
x-related:
|
||||
- title: Set up InfluxDB
|
||||
href: /influxdb/v2/get-started/
|
||||
- name: Signin
|
||||
description: Create a user session by signing in with username and password credentials.
|
||||
- name: Signout
|
||||
description: End a user session by signing out.
|
||||
- name: Sources
|
||||
- description: "The following table shows the most common operations that the InfluxDB `/api/v2` API supports.\nSome resources may support other operations that perform functions more specific to those resources.\nFor example, you can use the `PATCH /api/v2/scripts` endpoint to update properties of a script\nresource.\n\n| Operation | |\n|:----------|:-----------------------------------------------------------------------|\n| Write | Writes (`POST`) data to a bucket. |\n| Run | Executes (`POST`) a query or script and returns the result. |\n| List |\tRetrieves (`GET`) a list of zero or more resources. |\n| Create |\tCreates (`POST`) a new resource and returns the resource. |\n| Update |\tModifies (`PUT`) an existing resource to reflect data in your request. |\n| Delete |\tRemoves (`DELETE`) a specific resource. |\n"
|
||||
description: Manage data sources configured in InfluxDB OSS v2.
|
||||
- description: Overview of the common CRUD operations supported by the InfluxDB OSS v2 API.
|
||||
name: Supported operations
|
||||
x-traitTag: true
|
||||
- name: System information endpoints
|
||||
- description: |
|
||||
Process and analyze your data with [tasks](/influxdb/v2/reference/glossary/#task)
|
||||
in the InfluxDB task engine.
|
||||
Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.
|
||||
|
||||
To configure a task, provide the script and the schedule to run the task.
|
||||
For examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).
|
||||
|
||||
<span id="tasks-schemaref-task" />
|
||||
|
||||
### Properties
|
||||
|
||||
A `task` object contains information about an InfluxDB task resource.
|
||||
|
||||
The following table defines the properties that appear in a `task` object:
|
||||
|
||||
<SchemaDefinition schemaRef="#/components/schemas/Task" />
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Get started with tasks](/influxdb/v2/process-data/get-started/)
|
||||
- [Common data processing tasks](/influxdb/v2/process-data/common-tasks/)
|
||||
description: Endpoints for retrieving system-level information about the InfluxDB OSS v2 instance.
|
||||
- description: Schedule and manage Flux tasks that process and transform data on a recurring basis in InfluxDB OSS v2.
|
||||
name: Tasks
|
||||
x-related:
|
||||
- title: Get started with tasks
|
||||
href: /influxdb/v2/process-data/get-started/
|
||||
- name: Telegraf Plugins
|
||||
description: Retrieve available Telegraf plugin configuration templates for use with InfluxDB OSS v2.
|
||||
- name: Telegrafs
|
||||
- description: |
|
||||
Export and apply InfluxDB **templates**.
|
||||
Manage **stacks** of templated InfluxDB resources.
|
||||
|
||||
InfluxDB templates are prepackaged configurations for
|
||||
everything from dashboards and Telegraf to notifications and alerts.
|
||||
Use InfluxDB templates to quickly configure a fresh instance of InfluxDB,
|
||||
back up your dashboard configuration, or share your configuration with the
|
||||
InfluxData community.
|
||||
|
||||
Use the `/api/v2/templates` endpoints to export templates and apply templates.
|
||||
|
||||
**InfluxDB stacks** are stateful InfluxDB templates that let you
|
||||
add, update, and remove installed template resources over time, avoid duplicating
|
||||
resources when applying the same or similar templates more than once, and
|
||||
apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.
|
||||
|
||||
Use the `/api/v2/stacks` endpoints to manage installed template resources.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [InfluxDB stacks](/influxdb/v2/influxdb-templates/stacks/)
|
||||
- [InfluxDB templates](/influxdb/v2/influxdb-templates/)
|
||||
description: Create and manage Telegraf agent configurations that collect and write data to InfluxDB OSS v2.
|
||||
- description: Export and apply InfluxDB templates, and manage template stacks for InfluxDB OSS v2.
|
||||
name: Templates
|
||||
- description: |
|
||||
Manage users for your organization.
|
||||
Users are those with access to InfluxDB.
|
||||
To grant a user permission to access data, add them as a member of an
|
||||
organization and provide them with an API token.
|
||||
|
||||
### User sessions with authorizations
|
||||
|
||||
Optionally, you can scope an authorization (and its API token) to a user.
|
||||
If a user signs in with username and password, creating a _user session_,
|
||||
the session carries the permissions granted by all the user's authorizations.
|
||||
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Manage users](/influxdb/v2/influxdb/v2/users/)
|
||||
- [Create a token scoped to a user](/influxdb/v2/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)
|
||||
x-related:
|
||||
- title: InfluxDB templates
|
||||
href: /influxdb/v2/influxdb-templates/
|
||||
- description: Create and manage users that have access to InfluxDB OSS v2 organizations and resources.
|
||||
name: Users
|
||||
x-related:
|
||||
- title: Manage users
|
||||
href: /influxdb/v2/users/
|
||||
- name: Variables
|
||||
description: Create and manage variables for use in InfluxDB OSS v2 dashboards.
|
||||
- name: Views
|
||||
- description: |
|
||||
Write time series data to [buckets](/influxdb/v2/reference/glossary/#bucket).
|
||||
description: Manage cell views within InfluxDB OSS v2 dashboards.
|
||||
- description: Write time series data to InfluxDB OSS v2 buckets in line protocol format using the `/api/v2/write` endpoint.
|
||||
name: Write data
|
||||
x-related:
|
||||
- title: Write data
|
||||
href: /influxdb/v2/write-data/
|
||||
- name: Write data (v1-compatible)
|
||||
description: Write data to InfluxDB OSS v2 using the v1-compatible `/write` endpoint with line protocol.
|
||||
paths:
|
||||
/api/v2:
|
||||
get:
|
||||
|
|
@ -13309,7 +13126,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
$ref: '#/components/schemas/Error'
|
||||
description: The request was well-formed, but some points were rejected due to semantic errors--for example, schema conflicts or retention policy violations. Error message contains details for one or more rejected points.
|
||||
'429':
|
||||
description: Token is temporarily over quota. The Retry-After header describes when to try the write again.
|
||||
|
|
|
|||
|
|
@ -16,6 +16,8 @@ info:
|
|||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
x-influxdata-short-title: v2 API
|
||||
x-influxdata-short-description: The InfluxDB v2 HTTP API provides a v2-compatible programmatic interface for writing and managing data stored in an InfluxDB 3 Cloud Dedicated database.
|
||||
servers:
|
||||
- url: https://{baseurl}
|
||||
description: InfluxDB 3 Cloud Dedicated API URL
|
||||
|
|
@ -31,169 +33,45 @@ security:
|
|||
- BasicAuthentication: []
|
||||
- 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:
|
||||
|
||||
- `/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 line protocol format and process data the same way.
|
||||
|
||||
### Query data
|
||||
|
||||
InfluxDB 3 Cloud Dedicated provides the following protocols for executing a query:
|
||||
|
||||
- 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 `/api/v2/write` endpoint works with Bearer and Token authentication
|
||||
and existing InfluxDB 2.x tools and code.
|
||||
|
||||
### InfluxDB v1 compatibility
|
||||
|
||||
The `/write` and `/query` endpoints work with InfluxDB 1.x username/password
|
||||
authentication and existing InfluxDB 1.x tools and code.
|
||||
- description: Overview of the InfluxDB v1 and v2 compatible write and query endpoints available in InfluxDB 3 Cloud Dedicated.
|
||||
name: API compatibility
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Authenticate API requests using tokens, basic auth, or query strings.
|
||||
|
||||
## 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> -->
|
||||
- description: Authenticate API requests to InfluxDB 3 Cloud Dedicated using database tokens with bearer, token, basic, or querystring authentication schemes.
|
||||
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.
|
||||
|
||||
### Common parameters
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `database`, `db` | string | The database name |
|
||||
- description: Common query parameters used by InfluxDB 3 Cloud Dedicated API endpoints, including the required `database` or `db` parameter.
|
||||
name: Common parameters
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
||||
the `POST /api/v2/write` endpoint accepts the `Content-Encoding` header to indicate the compression applied to line protocol in the request body.
|
||||
|
||||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `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. |
|
||||
- description: Standard HTTP request headers used by InfluxDB 3 Cloud Dedicated API endpoints, including `Accept`, `Authorization`, `Content-Length`, and `Content-Type`.
|
||||
name: Headers
|
||||
x-traitTag: true
|
||||
- name: Ping
|
||||
- description: |
|
||||
Query data stored in a database.
|
||||
|
||||
- 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.
|
||||
description: Check the availability of the InfluxDB 3 Cloud Dedicated instance.
|
||||
- description: Query data stored in InfluxDB 3 Cloud Dedicated using InfluxQL via the v1-compatible `/query` endpoint. Use Flight+gRPC for SQL or InfluxQL queries with Arrow format output.
|
||||
name: Query data
|
||||
x-influxdatadocs-related:
|
||||
- /influxdb3/cloud-dedicated/get-started/query/
|
||||
- /influxdb3/cloud-dedicated/query-data/execute-queries/
|
||||
- description: |
|
||||
Get started with the InfluxDB 3 Cloud Dedicated API:
|
||||
|
||||
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.
|
||||
x-related:
|
||||
- title: Get started querying InfluxDB
|
||||
href: /influxdb3/cloud-dedicated/get-started/query/
|
||||
- title: Execute queries
|
||||
href: /influxdb3/cloud-dedicated/query-data/execute-queries/
|
||||
- description: Get started authenticating, creating a database, and writing and querying data with the InfluxDB 3 Cloud Dedicated API.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP status codes for success and failure responses.
|
||||
The response body may include additional details.
|
||||
For details about a specific operation's response,
|
||||
see **Responses** and **Response Samples** for that operation.
|
||||
|
||||
API operations may return the following HTTP status codes:
|
||||
|
||||
| Code | Status | Description |
|
||||
|:-----------:|:------------------------ |:--------------------- |
|
||||
| `200` | Success | |
|
||||
| `201` | Created | One or more resources are created. The response body contains details about the resource. |
|
||||
| `204` | No content | The request is successful and no data is returned. For example, The [`/write` and `/api/v2/write` endpoints](#tag/Write) return this status code if all data in the batch is written and queryable. |
|
||||
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: <ul><li>[Rejected points](/influxdb3/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points)</li><li>`Authorization` header is missing or malformed or the API token doesn't have permission for the operation.</li></ul> |
|
||||
| `401` | Unauthorized | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/)</li></ul> |
|
||||
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
|
||||
| `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. |
|
||||
| `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
|
||||
| `500` | Internal server error | |
|
||||
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
|
||||
- description: Standard HTTP status codes returned by InfluxDB 3 Cloud Dedicated API endpoints and their meanings.
|
||||
name: Response codes
|
||||
x-traitTag: true
|
||||
- name: System information endpoints
|
||||
description: Endpoints for retrieving system-level information about the InfluxDB 3 Cloud Dedicated instance.
|
||||
- name: Usage
|
||||
- description: |
|
||||
Write time series data to [databases](/influxdb3/cloud-dedicated/admin/databases/) using InfluxDB v1 or v2 endpoints.
|
||||
description: Retrieve usage metrics for an InfluxDB 3 Cloud Dedicated instance.
|
||||
- description: Write time series data to InfluxDB 3 Cloud Dedicated databases using the v2-compatible `/api/v2/write` endpoint or the v1-compatible `/write` endpoint with line protocol.
|
||||
name: Write data
|
||||
x-related:
|
||||
- title: Write data
|
||||
href: /influxdb3/cloud-dedicated/write-data/
|
||||
paths:
|
||||
/ping:
|
||||
get:
|
||||
|
|
@ -456,7 +334,6 @@ paths:
|
|||
Service unavailable.
|
||||
|
||||
- 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 using the InfluxDB v2 HTTP API
|
||||
|
|
|
|||
|
|
@ -15,6 +15,7 @@ info:
|
|||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
x-influxdata-short-title: Management API
|
||||
servers:
|
||||
- url: https://{baseurl}/api/v0
|
||||
description: InfluxDB 3 Cloud Dedicated Management API URL
|
||||
|
|
@ -29,46 +30,40 @@ security:
|
|||
bearerAuthJwt: []
|
||||
tags:
|
||||
- name: Database tokens
|
||||
description: Manage database read/write tokens for a cluster
|
||||
description: Create and manage database tokens that authorize read and write access to InfluxDB 3 Cloud Dedicated databases.
|
||||
x-related:
|
||||
- title: Manage database tokens
|
||||
href: /influxdb3/cloud-dedicated/admin/tokens/database/
|
||||
- title: Delete a database token
|
||||
href: /influxdb3/cloud-dedicated/admin/tokens/database/delete/
|
||||
- title: Authenticate Telegraf using tokens in your OS secret store
|
||||
href: https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os
|
||||
- name: Databases
|
||||
description: Manage databases for a cluster
|
||||
description: Create and manage databases in an InfluxDB 3 Cloud Dedicated cluster, including setting retention periods and custom partition templates.
|
||||
x-related:
|
||||
- title: Manage databases
|
||||
href: /influxdb3/cloud-dedicated/admin/databases/
|
||||
- title: Custom partitions
|
||||
href: /influxdb3/cloud-dedicated/admin/custom-partitions/
|
||||
- title: Partition templates
|
||||
href: /influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/
|
||||
- name: Quick start
|
||||
x-traitTag: true
|
||||
description: |
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
1. Create a management token using `influxctl token create`.
|
||||
|
||||
2. Create a database using the Management API.
|
||||
|
||||
```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"}'
|
||||
```
|
||||
|
||||
3. Create a database token for read/write access.
|
||||
|
||||
```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"}]}'
|
||||
```
|
||||
|
||||
4. Write data to InfluxDB Cloud Dedicated.
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
5. Query data using SQL or InfluxQL with a Flight client or the HTTP API.
|
||||
|
||||
description: Get started creating a database, issuing tokens, and writing data with the InfluxDB 3 Cloud Dedicated Management API.
|
||||
x-related:
|
||||
- title: Get started with Cloud Dedicated
|
||||
href: /influxdb3/cloud-dedicated/get-started/
|
||||
- title: Set up your cluster
|
||||
href: /influxdb3/cloud-dedicated/get-started/setup/
|
||||
- name: Tables
|
||||
description: Manage tables in a database
|
||||
description: Manage tables in an InfluxDB 3 Cloud Dedicated database, including creating tables with custom column schemas.
|
||||
x-related:
|
||||
- title: Manage tables
|
||||
href: /influxdb3/cloud-dedicated/admin/tables/
|
||||
- title: Create a table with custom partitioning
|
||||
href: /influxdb3/cloud-dedicated/admin/tables/#create-a-table-with-custom-partitioning
|
||||
- title: Custom partitions
|
||||
href: /influxdb3/cloud-dedicated/admin/custom-partitions/
|
||||
paths:
|
||||
/accounts/{accountId}/clusters/{clusterId}/databases:
|
||||
get:
|
||||
|
|
|
|||
|
|
@ -16,6 +16,8 @@ info:
|
|||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
x-influxdata-short-title: v2 API
|
||||
x-influxdata-short-description: The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
|
||||
servers:
|
||||
- url: https://{baseurl}
|
||||
description: InfluxDB 3 Cloud Serverless API URL
|
||||
|
|
@ -28,365 +30,125 @@ servers:
|
|||
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:
|
||||
|
||||
- `/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 line protocol format and process data the same way.
|
||||
|
||||
### Query data
|
||||
|
||||
InfluxDB 3 Cloud Serverless provides the following protocols for executing a query:
|
||||
|
||||
- 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 `/api/v2/write` endpoint works with Token authentication and existing
|
||||
InfluxDB 2.x tools and code.
|
||||
|
||||
### InfluxDB v1 compatibility
|
||||
|
||||
The `/write` and `/query` endpoints work with InfluxDB 1.x username/password
|
||||
authentication and existing InfluxDB 1.x tools and code.
|
||||
- description: Overview of the InfluxDB v1 and v2 compatible write and query endpoints available in InfluxDB 3 Cloud Serverless.
|
||||
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)
|
||||
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
- description: Authenticate API requests to InfluxDB 3 Cloud Serverless using API tokens with token, basic, or querystring authentication schemes.
|
||||
name: Authentication
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Create and manage authorizations (API tokens).
|
||||
|
||||
An _authorization_ contains a list of `read` and `write`
|
||||
permissions for organization resources and provides an API token for authentication.
|
||||
An authorization belongs to an organization and only contains permissions for that organization.
|
||||
|
||||
We recommend the following for managing your tokens:
|
||||
|
||||
- Create a generic user to create and manage tokens for writing data.
|
||||
- Store your tokens in a secure password vault for future access.
|
||||
|
||||
### User sessions with authorizations
|
||||
|
||||
Optionally, when creating an authorization, you can scope it to a specific user.
|
||||
If the user signs in with username and password, creating a _user session_,
|
||||
the session carries the permissions granted by all the user's authorizations.
|
||||
For more information, see [how to assign a token to a specific user](/influxdb3/cloud-serverless/security/tokens/create-token/).
|
||||
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
|
||||
|
||||
### Related endpoints
|
||||
|
||||
- [Signin](#tag/Signin)
|
||||
- [Signout](#tag/Signout)
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Authorize API requests](/influxdb3/cloud-serverless/api-guide/api_intro/#authentication)
|
||||
- [Manage API tokens](/influxdb3/cloud-serverless/security/tokens/)
|
||||
- [Assign a token to a specific user](/influxdb3/cloud-serverless/security/tokens/create-token/)
|
||||
- description: Create and manage API token authorizations that grant read and write permissions to InfluxDB 3 Cloud Serverless organization resources.
|
||||
name: Authorizations (API tokens)
|
||||
x-related:
|
||||
- title: Manage API tokens
|
||||
href: /influxdb3/cloud-serverless/security/tokens/
|
||||
- name: Bucket Schemas
|
||||
- description: |
|
||||
Store your data in InfluxDB [buckets](/influxdb3/cloud-serverless/reference/glossary/#bucket).
|
||||
A bucket is a named location where time series data is stored. All buckets
|
||||
have a [retention period](/influxdb3/cloud-serverless/reference/glossary/#retention-period),
|
||||
a duration of time that each data point persists. InfluxDB drops all
|
||||
points with timestamps older than the bucket’s retention period.
|
||||
A bucket belongs to an organization.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Manage buckets](/influxdb3/cloud-serverless/admin/buckets/)
|
||||
description: Manage explicit schemas for InfluxDB 3 Cloud Serverless buckets to enforce column names and data types.
|
||||
- description: Create and manage named storage locations (buckets) in InfluxDB 3 Cloud Serverless, each with a configurable retention period.
|
||||
name: Buckets
|
||||
x-related:
|
||||
- title: Manage buckets
|
||||
href: /influxdb3/cloud-serverless/admin/buckets/
|
||||
- name: Cells
|
||||
description: Manage cells within InfluxDB 3 Cloud Serverless dashboards.
|
||||
- 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).
|
||||
|
||||
### Common parameters
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `bucket` | string | The bucket name or ID ([find your bucket](/influxdb3/cloud-serverless/admin/buckets/view-buckets/). |
|
||||
| `bucketID` | string | The bucket ID ([find your bucket](/influxdb3/cloud-serverless/admin/buckets/view-buckets/). |
|
||||
| `org` | string | The organization name or ID ([find your organization](/influxdb3/cloud-serverless/admin/organizations/view-orgs/). |
|
||||
| `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb3/cloud-serverless/admin/organizations/view-orgs/). |
|
||||
description: Create and manage monitoring checks that query data and generate notification statuses in InfluxDB 3 Cloud Serverless.
|
||||
- description: Common query parameters used by InfluxDB 3 Cloud Serverless API endpoints, including `bucket`, `bucketID`, `org`, and `orgID`.
|
||||
name: Common parameters
|
||||
x-traitTag: true
|
||||
- name: Config
|
||||
description: Retrieve configuration information for an InfluxDB 3 Cloud Serverless instance.
|
||||
- name: Dashboards
|
||||
- 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).
|
||||
InfluxDB 2.x replaces databases and retention policies with buckets.
|
||||
To support InfluxDB 1.x query and write patterns in InfluxDB 2.x,
|
||||
databases and retention policies are mapped to buckets using the
|
||||
database and retention policy (DBRP) mapping service.
|
||||
The DBRP mapping service uses the database and retention policy
|
||||
specified in 1.x compatibility API requests to route operations to a bucket.
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/)
|
||||
description: Create and manage dashboards in InfluxDB 3 Cloud Serverless.
|
||||
- description: Manage database and retention policy (DBRP) mappings that route InfluxDB v1-compatible requests to InfluxDB 3 Cloud Serverless buckets.
|
||||
name: DBRPs
|
||||
- description: |
|
||||
Delete data from an InfluxDB bucket.
|
||||
x-related:
|
||||
- title: Database and retention policy mapping
|
||||
href: /influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/
|
||||
- description: Delete time series data from an InfluxDB 3 Cloud Serverless bucket by specifying a time range and optional predicate.
|
||||
name: Delete
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
||||
the `POST /api/v2/write` endpoint accepts the `Content-Encoding` header to indicate the compression applied to line protocol in the request body.
|
||||
|
||||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `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. |
|
||||
- description: Standard HTTP request headers used by InfluxDB 3 Cloud Serverless API endpoints, including `Accept`, `Authorization`, `Content-Length`, and `Content-Type`.
|
||||
name: Headers
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Store, manage, and execute scripts in InfluxDB.
|
||||
A script stores your custom Flux script and provides an invokable
|
||||
endpoint that accepts runtime parameters.
|
||||
In a script, you can specify custom runtime parameters
|
||||
(`params`)--for example, `params.myparameter`.
|
||||
Once you create a script, InfluxDB generates an
|
||||
[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)
|
||||
for your organization.
|
||||
You can run the script from API requests and tasks, defining parameter
|
||||
values for each run.
|
||||
When the script runs, InfluxDB replaces `params` references in the
|
||||
script with the runtime parameter values you define.
|
||||
|
||||
Use the `/api/v2/scripts` endpoints to create and manage scripts.
|
||||
See related guides to learn how to define parameters and execute scripts.
|
||||
|
||||
<!-- TSM-only -->
|
||||
- description: Store, manage, and execute custom Flux scripts in InfluxDB 3 Cloud Serverless. Scripts accept runtime parameters and can be invoked via dedicated endpoints.
|
||||
name: Invokable Scripts
|
||||
- name: Labels
|
||||
description: Create and manage labels for organizing InfluxDB 3 Cloud Serverless resources.
|
||||
- name: Legacy Authorizations
|
||||
description: Manage legacy (v1-compatible) authorization credentials in InfluxDB 3 Cloud Serverless.
|
||||
- name: Limits
|
||||
description: Retrieve rate limits and usage quotas for an InfluxDB 3 Cloud Serverless organization.
|
||||
- name: NotificationEndpoints
|
||||
description: Create and manage notification endpoints that receive alert notifications from InfluxDB 3 Cloud Serverless monitoring checks.
|
||||
- name: NotificationRules
|
||||
- description: |
|
||||
Manage your [organization](/influxdb3/cloud-serverless/reference/glossary/#organization).
|
||||
An organization is a workspace for a group of users. Organizations can be
|
||||
used to separate different environments, projects, teams or users within
|
||||
InfluxDB.
|
||||
|
||||
Use the `/api/v2/orgs` endpoints to view and manage organizations.
|
||||
description: Create and manage notification rules that define when and how InfluxDB 3 Cloud Serverless sends notifications to endpoints.
|
||||
- description: View and manage InfluxDB 3 Cloud Serverless organizations, which are workspaces that group users, buckets, and resources.
|
||||
name: Organizations
|
||||
- description: |
|
||||
Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `limit` | integer | The maximum number of records to return (after other parameters are applied). |
|
||||
| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |
|
||||
| `after` | string (resource ID) | Only returns resources created after the specified resource. |
|
||||
|
||||
### Limitations
|
||||
|
||||
- For specific endpoint parameters and examples, see the endpoint definition.
|
||||
- If you specify an `offset` parameter value greater than the total number of records,
|
||||
then InfluxDB returns an empty list in the response
|
||||
(given `offset` skips the specified number of records).
|
||||
|
||||
The following example passes `offset=50` to skip the first 50 results,
|
||||
but the user only has 10 buckets:
|
||||
|
||||
```sh
|
||||
curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" \
|
||||
--header "Authorization: Token INFLUX_API_TOKEN"
|
||||
```
|
||||
|
||||
The response contains the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"links": {
|
||||
"prev": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=49\u0026orgID=ORG_ID",
|
||||
"self": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=50\u0026orgID=ORG_ID"
|
||||
},
|
||||
"buckets": []
|
||||
}
|
||||
```
|
||||
x-related:
|
||||
- title: View and manage organizations
|
||||
href: /influxdb3/cloud-serverless/admin/
|
||||
- description: Query parameters for paginating results from list operations in the InfluxDB 3 Cloud Serverless API.
|
||||
name: Pagination
|
||||
x-traitTag: true
|
||||
- name: Ping
|
||||
- description: |
|
||||
Query data stored in a bucket.
|
||||
|
||||
- HTTP clients can query the v1 [`/query` endpoint](/influxdb3/cloud-serverless/api/#operation/GetLegacyQuery)
|
||||
using **InfluxQL** and retrieve data in **CSV** or **JSON** format.
|
||||
- _Flight + gRPC_ clients can query using **SQL** or **InfluxQL** and retrieve data in **Arrow** format.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Get started querying InfluxDB](/influxdb3/cloud-serverless/get-started/query/)
|
||||
- [Execute queries](/influxdb3/cloud-serverless/query-data/execute-queries/)
|
||||
description: Check the availability of the InfluxDB 3 Cloud Serverless instance.
|
||||
- description: Query data stored in InfluxDB 3 Cloud Serverless using InfluxQL via the v1-compatible `/query` endpoint, or using SQL and InfluxQL via Flight+gRPC clients.
|
||||
name: Query data
|
||||
- description: |
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
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.
|
||||
x-related:
|
||||
- title: Get started querying InfluxDB
|
||||
href: /influxdb3/cloud-serverless/get-started/query/
|
||||
- title: Execute queries
|
||||
href: /influxdb3/cloud-serverless/query-data/execute-queries/
|
||||
- description: Get started writing and querying data with the InfluxDB 3 Cloud Serverless API.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- name: Resources
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP status codes for success and failure responses.
|
||||
The response body may include additional details.
|
||||
For details about a specific operation's response,
|
||||
see **Responses** and **Response Samples** for that operation.
|
||||
|
||||
API operations may return the following HTTP status codes:
|
||||
|
||||
| Code | Status | Description |
|
||||
|:-----------:|:------------------------ |:--------------------- |
|
||||
| `200` | Success | |
|
||||
| `201` | Created | Successfully created a resource. The response body may contain details, for example [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) response bodies contain details of partial write failures. |
|
||||
| `204` | No content | The request succeeded. |
|
||||
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: <ul><li>Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected.</li><li>The batch contains a point with the same series as other points, but one of the field values has a different data type.<li>`Authorization` header is missing or malformed or the API token doesn't have permission for the operation.</li></ul> |
|
||||
| `401` | Unauthorized | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb3/cloud-serverless/security/tokens/)</li></ul> |
|
||||
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
|
||||
| `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. |
|
||||
| `413` | Request entity too large | Request payload exceeds the size limit. |
|
||||
| `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
|
||||
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
|
||||
| `500` | Internal server error | |
|
||||
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
|
||||
description: Retrieve a list of top-level resource types available in the InfluxDB 3 Cloud Serverless API.
|
||||
- description: Standard HTTP status codes returned by InfluxDB 3 Cloud Serverless API endpoints and their meanings.
|
||||
name: Response codes
|
||||
x-traitTag: true
|
||||
- name: Routes
|
||||
description: Retrieve top-level routes for the InfluxDB 3 Cloud Serverless API.
|
||||
- name: Rules
|
||||
description: Manage notification rules in InfluxDB 3 Cloud Serverless.
|
||||
- name: Secrets
|
||||
description: Create and manage secrets (key-value pairs) for use in InfluxDB 3 Cloud Serverless Flux scripts and tasks.
|
||||
- name: Security and access endpoints
|
||||
description: Endpoints for managing authentication and access control in InfluxDB 3 Cloud Serverless.
|
||||
- name: Setup
|
||||
description: Configure an initial InfluxDB 3 Cloud Serverless instance, including creating the initial user, organization, and bucket.
|
||||
- name: Signin
|
||||
description: Create a user session by signing in with username and password credentials.
|
||||
- name: Signout
|
||||
- description: "The following table shows the most common operations that the InfluxDB `/api/v2` API supports.\nSome resources may support other operations that perform functions more specific to those resources.\nFor example, you can use the `PATCH /api/v2/scripts` endpoint to update properties of a script\nresource.\n\n| Operation | |\n|:----------|:-----------------------------------------------------------------------|\n| Write | Writes (`POST`) data to a bucket. |\n| Run | Executes (`POST`) a query or script and returns the result. |\n| List |\tRetrieves (`GET`) a list of zero or more resources. |\n| Create |\tCreates (`POST`) a new resource and returns the resource. |\n| Update |\tModifies (`PUT`) an existing resource to reflect data in your request. |\n| Delete |\tRemoves (`DELETE`) a specific resource. |\n"
|
||||
description: End a user session by signing out.
|
||||
- description: Overview of the common CRUD operations supported by the InfluxDB 3 Cloud Serverless API.
|
||||
name: Supported operations
|
||||
x-traitTag: true
|
||||
- name: System information endpoints
|
||||
- description: |
|
||||
Process and analyze your data with tasks
|
||||
in the InfluxDB task engine.
|
||||
Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.
|
||||
|
||||
To configure a task, provide the script and the schedule to run the task.
|
||||
For examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).
|
||||
|
||||
<span id="tasks-schemaref-task" />
|
||||
|
||||
### Properties
|
||||
|
||||
A `task` object contains information about an InfluxDB task resource.
|
||||
|
||||
The following table defines the properties that appear in this object:
|
||||
|
||||
<SchemaDefinition schemaRef="#/components/schemas/Task" />
|
||||
|
||||
<!-- TSM-only -->
|
||||
description: Endpoints for retrieving system-level information about the InfluxDB 3 Cloud Serverless instance.
|
||||
- description: Schedule and manage Flux tasks that process and transform data on a recurring basis in InfluxDB 3 Cloud Serverless.
|
||||
name: Tasks
|
||||
- name: Telegraf Plugins
|
||||
description: Retrieve available Telegraf plugin configuration templates for use with InfluxDB 3 Cloud Serverless.
|
||||
- name: Telegrafs
|
||||
- description: |
|
||||
Export and apply InfluxDB **templates**.
|
||||
Manage **stacks** of templated InfluxDB resources.
|
||||
|
||||
InfluxDB templates are prepackaged configurations for resources.
|
||||
Use InfluxDB templates to configure a fresh instance of InfluxDB,
|
||||
back up your dashboard configuration, or share your configuration.
|
||||
|
||||
Use the `/api/v2/templates` endpoints to export templates and apply templates.
|
||||
|
||||
**InfluxDB stacks** are stateful InfluxDB templates that let you
|
||||
add, update, and remove installed template resources over time, avoid duplicating
|
||||
resources when applying the same or similar templates more than once, and
|
||||
apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.
|
||||
|
||||
Use the `/api/v2/stacks` endpoints to manage installed template resources.
|
||||
|
||||
<!-- TSM-only -->
|
||||
description: Create and manage Telegraf agent configurations that collect and write data to InfluxDB 3 Cloud Serverless.
|
||||
- description: Export and apply InfluxDB templates, and manage template stacks for InfluxDB 3 Cloud Serverless.
|
||||
name: Templates
|
||||
- name: Usage
|
||||
- description: |
|
||||
Retrieve specific users.
|
||||
|
||||
InfluxDB Cloud lets you invite and collaborate with multiple users in your organization.
|
||||
To invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);
|
||||
you can't use the InfluxDB API to manage users in InfluxDB Cloud.
|
||||
Once a user is added to your organization, you can use the
|
||||
`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to
|
||||
view specific members.
|
||||
|
||||
### User sessions with authorizations
|
||||
|
||||
Optionally, you can scope an authorization (and its API token) to a user.
|
||||
If a user signs in with username and password, creating a _user session_,
|
||||
the session carries the permissions granted by all the user's authorizations.
|
||||
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
|
||||
|
||||
### Related guides
|
||||
|
||||
- [Manage users](/influxdb3/cloud-serverless/organizations/users/)
|
||||
description: Retrieve usage metrics and cardinality data for an InfluxDB 3 Cloud Serverless organization.
|
||||
- description: View specific users that are members of your InfluxDB 3 Cloud Serverless organization.
|
||||
name: Users
|
||||
x-related:
|
||||
- title: Manage users
|
||||
href: /influxdb3/cloud-serverless/organizations/users/
|
||||
- name: Variables
|
||||
description: Create and manage variables for use in InfluxDB 3 Cloud Serverless dashboards.
|
||||
- name: Views
|
||||
- description: |
|
||||
Write time series data to [buckets](/influxdb3/cloud-serverless/reference/glossary/#bucket) using InfluxDB v1 or v2 endpoints.
|
||||
description: Manage cell views within InfluxDB 3 Cloud Serverless dashboards.
|
||||
- description: Write time series data to InfluxDB 3 Cloud Serverless buckets using the v2-compatible `/api/v2/write` endpoint or the v1-compatible `/write` endpoint with line protocol.
|
||||
name: Write data
|
||||
x-related:
|
||||
- title: Write data
|
||||
href: /influxdb3/cloud-serverless/write-data/
|
||||
paths:
|
||||
/api/v2:
|
||||
get:
|
||||
|
|
|
|||
|
|
@ -16,6 +16,8 @@ info:
|
|||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
x-influxdata-short-title: v2 API
|
||||
x-influxdata-short-description: The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
|
||||
servers:
|
||||
- url: https://{baseurl}
|
||||
description: InfluxDB 3 Clustered API URL
|
||||
|
|
@ -31,170 +33,45 @@ security:
|
|||
- BasicAuthentication: []
|
||||
- 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:
|
||||
|
||||
- `/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 line protocol format and process data the same way.
|
||||
|
||||
### Query data
|
||||
|
||||
InfluxDB 3 Clustered provides the following protocols for executing a query:
|
||||
|
||||
- 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 `/api/v2/write` endpoint works with Bearer and Token authentication
|
||||
and existing InfluxDB 2.x tools and code.
|
||||
|
||||
### InfluxDB v1 compatibility
|
||||
|
||||
The `/write` and `/query` endpoints work with InfluxDB 1.x username/password
|
||||
authentication and existing InfluxDB 1.x tools and code.
|
||||
- description: Overview of the InfluxDB v1 and v2 compatible write and query endpoints available in InfluxDB 3 Clustered.
|
||||
name: API compatibility
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
Authenticate API requests using tokens, basic auth, or query strings.
|
||||
|
||||
## 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> -->
|
||||
- description: Authenticate API requests to InfluxDB 3 Clustered using database tokens with bearer, token, basic, or querystring authentication schemes.
|
||||
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.
|
||||
|
||||
### Common parameters
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `database`, `db` | string | The database name |
|
||||
- description: Common query parameters used by InfluxDB 3 Clustered API endpoints, including the required `database` or `db` parameter.
|
||||
name: Common parameters
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
||||
the `POST /api/v2/write` endpoint accepts the `Content-Encoding` header to indicate the compression applied to line protocol in the request body.
|
||||
|
||||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `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. |
|
||||
- description: Standard HTTP request headers used by InfluxDB 3 Clustered API endpoints, including `Accept`, `Authorization`, `Content-Length`, and `Content-Type`.
|
||||
name: Headers
|
||||
x-traitTag: true
|
||||
- name: Ping
|
||||
- description: |
|
||||
Query data stored in a database.
|
||||
|
||||
- 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.
|
||||
description: Check the availability of an InfluxDB 3 Clustered instance.
|
||||
- description: Query data stored in InfluxDB 3 Clustered using InfluxQL via the v1-compatible `/query` endpoint. Use Flight+gRPC for SQL or InfluxQL queries with Arrow format output.
|
||||
name: Query data
|
||||
x-influxdatadocs-related:
|
||||
- /influxdb3/clustered/get-started/query/
|
||||
- /influxdb3/clustered/query-data/execute-queries/
|
||||
- description: |
|
||||
Get started with the InfluxDB 3 Clustered API:
|
||||
|
||||
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.
|
||||
x-related:
|
||||
- title: Get started querying InfluxDB
|
||||
href: /influxdb3/clustered/get-started/query/
|
||||
- title: Execute queries
|
||||
href: /influxdb3/clustered/query-data/execute-queries/
|
||||
- description: Get started authenticating, creating a database, and writing and querying data with the InfluxDB 3 Clustered API.
|
||||
name: Quick start
|
||||
x-traitTag: true
|
||||
- description: |
|
||||
InfluxDB HTTP API endpoints use standard HTTP status codes for success and failure responses.
|
||||
The response body may include additional details.
|
||||
For details about a specific operation's response,
|
||||
see **Responses** and **Response Samples** for that operation.
|
||||
|
||||
API operations may return the following HTTP status codes:
|
||||
|
||||
| Code | Status | Description |
|
||||
|:-----------:|:------------------------ |:--------------------- |
|
||||
| `200` | Success | |
|
||||
| `204` | Success. No content | InfluxDB doesn't return data for the request. For example, a successful write request returns `204` status code, acknowledging that data is written and queryable. |
|
||||
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. If line protocol in the request body is malformed. The response body contains the first malformed line and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. |
|
||||
| `401` | Unauthorized | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage tokens](/influxdb3/clustered/admin/tokens/)</li></ul> |
|
||||
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
|
||||
| `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. |
|
||||
| `413` | Request entity too large | Request payload exceeds the size limit. |
|
||||
| `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
|
||||
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
|
||||
| `500` | Internal server error | |
|
||||
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
|
||||
- description: Standard HTTP status codes returned by InfluxDB 3 Clustered API endpoints and their meanings.
|
||||
name: Response codes
|
||||
x-traitTag: true
|
||||
- name: System information endpoints
|
||||
description: Endpoints for retrieving system-level information about the InfluxDB 3 Clustered instance.
|
||||
- name: Usage
|
||||
- description: |
|
||||
Write time series data to [databases](/influxdb3/clustered/admin/databases/) using InfluxDB v1 or v2 endpoints.
|
||||
description: Retrieve usage metrics for an InfluxDB 3 Clustered instance.
|
||||
- description: Write time series data to InfluxDB 3 Clustered databases using the v2-compatible `/api/v2/write` endpoint or the v1-compatible `/write` endpoint with line protocol.
|
||||
name: Write data
|
||||
x-related:
|
||||
- title: Write data
|
||||
href: /influxdb3/clustered/write-data/
|
||||
paths:
|
||||
/ping:
|
||||
get:
|
||||
|
|
|
|||
|
|
@ -15,6 +15,7 @@ info:
|
|||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
x-influxdata-short-title: Management API
|
||||
servers:
|
||||
- url: https://{baseurl}/api/v0
|
||||
description: InfluxDB 3 Clustered Management API URL
|
||||
|
|
@ -29,46 +30,34 @@ security:
|
|||
bearerAuthJwt: []
|
||||
tags:
|
||||
- name: Database tokens
|
||||
description: Manage database read/write tokens for a cluster
|
||||
description: Create and manage database tokens that authorize read and write access to InfluxDB 3 Clustered databases.
|
||||
x-related:
|
||||
- title: Manage database tokens
|
||||
href: /influxdb3/clustered/admin/tokens/database/
|
||||
- title: Delete a database token
|
||||
href: /influxdb3/clustered/admin/tokens/database/delete/
|
||||
- title: Authenticate Telegraf using tokens in your OS secret store
|
||||
href: https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os
|
||||
- name: Databases
|
||||
description: Manage databases for a cluster
|
||||
description: Create and manage databases in an InfluxDB 3 Clustered cluster, including setting retention periods and custom partition templates.
|
||||
x-related:
|
||||
- title: Manage databases
|
||||
href: /influxdb3/clustered/admin/databases/
|
||||
- title: Custom partitions
|
||||
href: /influxdb3/clustered/admin/custom-partitions/
|
||||
- name: Quick start
|
||||
x-traitTag: true
|
||||
description: |
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
1. Create a management token using `influxctl token create`.
|
||||
|
||||
2. Create a database using the Management API.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://CLUSTER_HOST/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/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 Clustered.
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
5. Query data using SQL or InfluxQL with a Flight client or the HTTP API.
|
||||
|
||||
description: Get started creating a database, issuing tokens, and writing data with the InfluxDB 3 Clustered Management API.
|
||||
x-related:
|
||||
- title: Get started with Clustered
|
||||
href: /influxdb3/clustered/get-started/
|
||||
- name: Tables
|
||||
description: Manage tables in a database
|
||||
description: Manage tables in an InfluxDB 3 Clustered database, including creating tables with custom column schemas.
|
||||
x-related:
|
||||
- title: Manage tables
|
||||
href: /influxdb3/clustered/admin/tables/
|
||||
- title: Custom partitions
|
||||
href: /influxdb3/clustered/admin/custom-partitions/
|
||||
paths:
|
||||
/databases:
|
||||
get:
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ x-influxdata-product-name: InfluxDB 3 Core
|
|||
|
||||
apis:
|
||||
v3@3:
|
||||
root: v3/influxdb3-core-openapi.yaml
|
||||
root: influxdb3-core-openapi.yaml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb3/core/api/
|
||||
- /influxdb3/core/api/v1/
|
||||
|
|
|
|||
|
|
@ -30,6 +30,12 @@ info:
|
|||
x-related:
|
||||
- title: Migrate from InfluxDB v1 or v2
|
||||
href: /influxdb3/core/get-started/migrate-from-influxdb-v1-v2/
|
||||
x-influxdata-short-title: InfluxDB 3 API
|
||||
x-influxdata-version-matrix:
|
||||
v1: Compatibility layer for InfluxDB 1.x clients (supported)
|
||||
v2: Compatibility layer for InfluxDB 2.x clients (supported)
|
||||
v3: Native API for InfluxDB 3.x (current)
|
||||
x-influxdata-short-description: The InfluxDB 3 HTTP API provides a programmatic interface for interactions with InfluxDB, including writing, querying, and processing data, and managing an InfluxDB 3 instance.
|
||||
servers:
|
||||
- url: https://{baseurl}
|
||||
description: InfluxDB 3 Core API URL
|
||||
|
|
@ -43,176 +49,61 @@ security:
|
|||
- BearerAuthentication: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: |
|
||||
Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API:
|
||||
|
||||
| Authentication scheme | Works with |
|
||||
|:----------------------|:-----------|
|
||||
| Bearer authentication | All endpoints |
|
||||
| Token authentication | v1 and v2 compatibility endpoints (`/write`, `/query`, `/api/v2/write`) |
|
||||
| Basic authentication | v1 compatibility endpoints (`/write`, `/query`) |
|
||||
| Querystring authentication | v1 compatibility endpoints (`/write`, `/query`) |
|
||||
|
||||
See the **Security Schemes** section below for details on each authentication method.
|
||||
description: Authenticate API requests using bearer tokens, token scheme, basic authentication, or querystring credentials. See the Security Schemes section for details on each method.
|
||||
x-traitTag: true
|
||||
- name: Cache distinct values
|
||||
description: |
|
||||
The Distinct Value Cache (DVC) lets you cache distinct
|
||||
values of one or more columns in a table, improving the performance of
|
||||
queries that return distinct tag and field values.
|
||||
|
||||
The DVC is an in-memory cache that stores distinct values for specific columns
|
||||
in a table. When you create a DVC, you can specify what columns' distinct
|
||||
values to cache, the maximum number of distinct value combinations to cache, and
|
||||
the maximum age of cached values. A DVC is associated with a table, which can
|
||||
have multiple DVCs.
|
||||
description: Manage the Distinct Value Cache (DVC), an in-memory cache that stores distinct values for specific columns in a table to improve query performance for distinct tag and field value lookups.
|
||||
x-related:
|
||||
- title: Manage the Distinct Value Cache
|
||||
href: /influxdb3/core/admin/distinct-value-cache/
|
||||
- name: Cache last value
|
||||
description: |
|
||||
The Last Value Cache (LVC) lets you cache the most recent
|
||||
values for specific fields in a table, improving the performance of queries that
|
||||
return the most recent value of a field for specific series or the last N values
|
||||
of a field.
|
||||
|
||||
The LVC is an in-memory cache that stores the last N number of values for
|
||||
specific fields of series in a table. When you create an LVC, you can specify
|
||||
what fields to cache, what tags to use to identify each series, and the
|
||||
number of values to cache for each unique series.
|
||||
An LVC is associated with a table, which can have multiple LVCs.
|
||||
description: Manage the Last Value Cache (LVC), an in-memory cache that stores the most recent N values for specific fields in a table to improve query performance for last-value lookups.
|
||||
x-related:
|
||||
- title: Manage the Last Value Cache
|
||||
href: /influxdb3/core/admin/last-value-cache/
|
||||
- name: Migrate from InfluxDB v1 or v2
|
||||
x-traitTag: true
|
||||
description: |
|
||||
Migrate your existing InfluxDB v1 or v2 workloads to InfluxDB 3 Core.
|
||||
|
||||
InfluxDB 3 provides compatibility endpoints that work with InfluxDB 1.x and 2.x client libraries and tools.
|
||||
Operations marked with <span class="api-compat-badge api-compat-badge--v1">v1</span> or <span class="api-compat-badge api-compat-badge--v2">v2</span> badges are compatible with the respective InfluxDB version.
|
||||
|
||||
### Migration guides
|
||||
|
||||
- [Migrate from InfluxDB v1](/influxdb3/core/guides/migrate/influxdb-1x/) - For users migrating from InfluxDB 1.x
|
||||
- [Migrate from InfluxDB v2](/influxdb3/core/guides/migrate/influxdb-2x/) - For users migrating from InfluxDB 2.x or Cloud
|
||||
- [Use compatibility APIs to write data](/influxdb3/core/write-data/http-api/compatibility-apis/) - v1 and v2 write endpoints
|
||||
- [Use the v1 HTTP query API](/influxdb3/core/query-data/execute-queries/influxdb-v1-api/) - InfluxQL queries via HTTP
|
||||
description: Reference information for migrating existing InfluxDB v1 or v2 workloads to InfluxDB 3 Core using compatibility endpoints.
|
||||
- name: Database
|
||||
description: Manage databases
|
||||
- description: |
|
||||
Most InfluxDB API endpoints require parameters in the request--for example, specifying the database to use.
|
||||
|
||||
### Common parameters
|
||||
|
||||
The following table shows common parameters used by many InfluxDB API endpoints.
|
||||
Many endpoints may require other parameters in the query string or in the
|
||||
request body that perform functions specific to those endpoints.
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `db` | string | The database name |
|
||||
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
||||
the write endpoints accept the `Content-Encoding` header to indicate that line protocol is compressed in the request body.
|
||||
|
||||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `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. |
|
||||
description: Create, list, and delete databases in InfluxDB 3 Core.
|
||||
x-related:
|
||||
- title: Manage databases
|
||||
href: /influxdb3/core/admin/databases/
|
||||
- description: Common HTTP request headers and query parameters used by InfluxDB 3 Core API endpoints.
|
||||
name: Headers and parameters
|
||||
x-traitTag: true
|
||||
- name: Processing engine
|
||||
description: |
|
||||
Manage Processing engine triggers, test plugins, and send requests to trigger On Request plugins.
|
||||
|
||||
InfluxDB 3 Core provides the InfluxDB 3 processing engine, an embedded Python VM that can dynamically load and trigger Python plugins in response to events in your database.
|
||||
Use Processing engine plugins and triggers to run code and perform tasks for different database events.
|
||||
|
||||
To get started with the processing engine, see the [Processing engine and Python plugins](/influxdb3/core/processing-engine/) guide.
|
||||
description: Manage Processing engine triggers, test plugins, and invoke On Request plugins. The processing engine is an embedded Python VM that runs plugins in response to database events.
|
||||
x-related:
|
||||
- title: Processing engine and Python plugins
|
||||
href: /influxdb3/core/processing-engine/
|
||||
- name: Query data
|
||||
description: Query data using SQL or InfluxQL
|
||||
description: Query data stored in InfluxDB 3 Core using SQL or InfluxQL.
|
||||
x-related:
|
||||
- title: Query data
|
||||
href: /influxdb3/core/query-data/
|
||||
- name: Quick start
|
||||
description: |
|
||||
Authenticate, write, and query with the API:
|
||||
|
||||
1. Create an admin token to authorize API requests.
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8181/api/v3/configure/token/admin"
|
||||
```
|
||||
2. Check the status of the InfluxDB server.
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8181/health" \
|
||||
--header "Authorization: Bearer ADMIN_TOKEN"
|
||||
```
|
||||
|
||||
3. Write data to InfluxDB.
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto"
|
||||
--header "Authorization: Bearer ADMIN_TOKEN" \
|
||||
--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`.
|
||||
|
||||
4. Query data from InfluxDB.
|
||||
|
||||
```bash
|
||||
curl -G "http://localhost:8181/api/v3/query_sql" \
|
||||
--header "Authorization: Bearer ADMIN_TOKEN" \
|
||||
--data-urlencode "db=sensors" \
|
||||
--data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \
|
||||
--data-urlencode "format=jsonl"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```jsonl
|
||||
{"room":"Living room","temp":71.5,"time":"2025-02-25T20:19:34.984098"}
|
||||
```
|
||||
|
||||
For more information about using InfluxDB 3 Core, see the [Get started](/influxdb3/core/get-started/) guide.
|
||||
description: Get started authenticating, writing, and querying data with the InfluxDB 3 Core API.
|
||||
x-traitTag: true
|
||||
- name: Server information
|
||||
description: Retrieve server metrics, status, and version information
|
||||
description: Retrieve server metrics, health status, and version information for InfluxDB 3 Core.
|
||||
- name: Table
|
||||
description: Manage table schemas and data
|
||||
description: Manage table schemas in an InfluxDB 3 Core database.
|
||||
x-related:
|
||||
- title: Manage tables
|
||||
href: /influxdb3/core/admin/tables/
|
||||
- name: Auth token
|
||||
description: Manage tokens for authentication and authorization
|
||||
description: Create and manage tokens used for authenticating and authorizing access to InfluxDB 3 Core resources.
|
||||
x-related:
|
||||
- title: Manage tokens
|
||||
href: /influxdb3/core/admin/tokens/
|
||||
- name: Write data
|
||||
x-related:
|
||||
- title: Write data using HTTP APIs
|
||||
href: /influxdb3/core/write-data/http-api/
|
||||
- title: Line protocol reference
|
||||
href: /influxdb3/core/reference/syntax/line-protocol/
|
||||
description: |
|
||||
Write data to InfluxDB 3 Core using line protocol format.
|
||||
|
||||
#### Timestamp precision across write APIs
|
||||
|
||||
InfluxDB 3 provides multiple write endpoints for compatibility with different InfluxDB versions.
|
||||
The following table compares timestamp precision support across v1, v2, and v3 write APIs:
|
||||
|
||||
| Precision | v1 (`/write`) | v2 (`/api/v2/write`) | v3 (`/api/v3/write_lp`) |
|
||||
|-----------|---------------|----------------------|-------------------------|
|
||||
| **Auto detection** | ❌ No | ❌ No | ✅ `auto` (default) |
|
||||
| **Seconds** | ✅ `s` | ✅ `s` | ✅ `second` |
|
||||
| **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `millisecond` |
|
||||
| **Microseconds** | ✅ `u` or `µ` | ✅ `us` | ✅ `microsecond` |
|
||||
| **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `nanosecond` |
|
||||
| **Minutes** | ✅ `m` | ❌ No | ❌ No |
|
||||
| **Hours** | ✅ `h` | ❌ No | ❌ No |
|
||||
| **Default** | Nanosecond | Nanosecond | **Auto** (guessed) |
|
||||
|
||||
All timestamps are stored internally as nanoseconds.
|
||||
description: Write time series data to InfluxDB 3 Core in line protocol format using the v1, v2, or v3 write endpoints.
|
||||
paths:
|
||||
/write:
|
||||
post:
|
||||
|
|
@ -1001,7 +892,7 @@ paths:
|
|||
description: The InfluxDB version number (for example, `3.8.0`).
|
||||
schema:
|
||||
type: string
|
||||
example: '3.8.0'
|
||||
example: 3.8.0
|
||||
x-influxdb-build:
|
||||
description: The InfluxDB build type (`Core` or `Enterprise`).
|
||||
schema:
|
||||
|
|
@ -1015,15 +906,15 @@ paths:
|
|||
version:
|
||||
type: string
|
||||
description: The InfluxDB version number.
|
||||
example: '3.8.0'
|
||||
example: 3.8.0
|
||||
revision:
|
||||
type: string
|
||||
description: The git revision hash for the build.
|
||||
example: '5276213d5b'
|
||||
example: 5276213d5b
|
||||
process_id:
|
||||
type: string
|
||||
description: A unique identifier for the server process.
|
||||
example: 'b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7'
|
||||
example: b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7
|
||||
'404':
|
||||
description: |
|
||||
Not Found. Returned for HEAD requests.
|
||||
|
|
@ -1747,7 +1638,7 @@ paths:
|
|||
$ref: '#/components/responses/Unauthorized'
|
||||
security:
|
||||
- BearerAuthentication: []
|
||||
- {} # No auth required for initial token creation
|
||||
- {}
|
||||
tags:
|
||||
- Auth token
|
||||
/api/v3/configure/token/admin/regenerate:
|
||||
|
|
@ -7,7 +7,7 @@ x-influxdata-product-name: InfluxDB 3 Enterprise
|
|||
|
||||
apis:
|
||||
v3@3:
|
||||
root: v3/influxdb3-enterprise-openapi.yaml
|
||||
root: influxdb3-enterprise-openapi.yaml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb3/enterprise/api/
|
||||
- /influxdb3/enterprise/api/v1/
|
||||
|
|
|
|||
|
|
@ -30,6 +30,12 @@ info:
|
|||
x-related:
|
||||
- title: Migrate from InfluxDB v1 or v2
|
||||
href: /influxdb3/enterprise/get-started/migrate-from-influxdb-v1-v2/
|
||||
x-influxdata-short-title: InfluxDB 3 API
|
||||
x-influxdata-version-matrix:
|
||||
v1: Compatibility layer for InfluxDB 1.x clients (supported)
|
||||
v2: Compatibility layer for InfluxDB 2.x clients (supported)
|
||||
v3: Native API for InfluxDB 3.x (current)
|
||||
x-influxdata-short-description: The InfluxDB 3 HTTP API provides a programmatic interface for interactions with InfluxDB, including writing, querying, and processing data, and managing an InfluxDB 3 instance.
|
||||
servers:
|
||||
- url: https://{baseurl}
|
||||
description: InfluxDB 3 Enterprise API URL
|
||||
|
|
@ -46,158 +52,55 @@ security:
|
|||
- QuerystringAuthentication: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: |
|
||||
Depending on your workflow, use one of the following schemes to authenticate to the InfluxDB 3 API:
|
||||
|
||||
| Authentication scheme | Works with |
|
||||
|:-------------------|:-----------|
|
||||
| Bearer authentication | All endpoints |
|
||||
| Token authentication | v1, v2 endpoints |
|
||||
| Basic authentication | v1 endpoints |
|
||||
| Querystring authentication | v1 endpoints |
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
description: Authenticate API requests using bearer tokens, token scheme, basic authentication, or querystring credentials. See the Security Schemes section for details on each method.
|
||||
x-traitTag: true
|
||||
- name: Cache data
|
||||
description: |
|
||||
Manage the in-memory cache.
|
||||
|
||||
#### Distinct Value Cache
|
||||
|
||||
The Distinct Value Cache (DVC) lets you cache distinct
|
||||
values of one or more columns in a table, improving the performance of
|
||||
queries that return distinct tag and field values.
|
||||
|
||||
The DVC is an in-memory cache that stores distinct values for specific columns
|
||||
in a table. When you create an DVC, you can specify what columns' distinct
|
||||
values to cache, the maximum number of distinct value combinations to cache, and
|
||||
the maximum age of cached values. A DVC is associated with a table, which can
|
||||
have multiple DVCs.
|
||||
|
||||
#### Last value cache
|
||||
|
||||
The Last Value Cache (LVC) lets you cache the most recent
|
||||
values for specific fields in a table, improving the performance of queries that
|
||||
return the most recent value of a field for specific series or the last N values
|
||||
of a field.
|
||||
|
||||
The LVC is an in-memory cache that stores the last N number of values for
|
||||
specific fields of series in a table. When you create an LVC, you can specify
|
||||
what fields to cache, what tags to use to identify each series, and the
|
||||
number of values to cache for each unique series.
|
||||
An LVC is associated with a table, which can have multiple LVCs.
|
||||
|
||||
#### Related guides
|
||||
|
||||
- [Manage the Distinct Value Cache](/influxdb3/enterprise/admin/distinct-value-cache/)
|
||||
- [Manage the Last Value Cache](/influxdb3/enterprise/admin/last-value-cache/)
|
||||
description: Manage in-memory caches for InfluxDB 3 Enterprise, including the Distinct Value Cache (DVC) for distinct column values and the Last Value Cache (LVC) for most-recent field values.
|
||||
x-related:
|
||||
- title: Manage the Distinct Value Cache
|
||||
href: /influxdb3/enterprise/admin/distinct-value-cache/
|
||||
- title: Manage the Last Value Cache
|
||||
href: /influxdb3/enterprise/admin/last-value-cache/
|
||||
- name: Database
|
||||
description: Manage databases
|
||||
- description: |
|
||||
Most InfluxDB API endpoints require parameters in the request--for example, specifying the database to use.
|
||||
|
||||
### Common parameters
|
||||
|
||||
The following table shows common parameters used by many InfluxDB API endpoints.
|
||||
Many endpoints may require other parameters in the query string or in the
|
||||
request body that perform functions specific to those endpoints.
|
||||
|
||||
| Query parameter | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `db` | string | The database name |
|
||||
|
||||
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
||||
The following table shows common headers used by many InfluxDB API endpoints.
|
||||
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
||||
the write endpoints accept the `Content-Encoding` header to indicate that line protocol is compressed in the request body.
|
||||
|
||||
| Header | Value type | Description |
|
||||
|:------------------------ |:--------------------- |:-------------------------------------------|
|
||||
| `Accept` | string | The content type that the client can understand. |
|
||||
| `Authorization` | string | The authorization scheme and credential. |
|
||||
| `Content-Length` | integer | The size of the entity-body, in bytes. |
|
||||
| `Content-Type` | string | The format of the data in the request body. |
|
||||
description: Create, list, and delete databases in InfluxDB 3 Enterprise.
|
||||
x-related:
|
||||
- title: Manage databases
|
||||
href: /influxdb3/enterprise/admin/databases/
|
||||
- description: Common HTTP request headers and query parameters used by InfluxDB 3 Enterprise API endpoints.
|
||||
name: Headers and parameters
|
||||
x-traitTag: true
|
||||
- name: Processing engine
|
||||
description: |
|
||||
Manage Processing engine triggers, test plugins, and send requests to trigger On Request plugins.
|
||||
|
||||
InfluxDB 3 Enterprise provides the InfluxDB 3 processing engine, an embedded Python VM that can dynamically load and trigger Python plugins in response to events in your database.
|
||||
Use Processing engine plugins and triggers to run code and perform tasks for different database events.
|
||||
|
||||
To get started with the processing engine, see the [Processing engine and Python plugins](/influxdb3/enterprise/processing-engine/) guide.
|
||||
description: Manage Processing engine triggers, test plugins, and invoke On Request plugins. The processing engine is an embedded Python VM that runs plugins in response to database events.
|
||||
x-related:
|
||||
- title: Processing engine and Python plugins
|
||||
href: /influxdb3/enterprise/processing-engine/
|
||||
- name: Query data
|
||||
description: Query data using SQL or InfluxQL
|
||||
description: Query data stored in InfluxDB 3 Enterprise using SQL or InfluxQL.
|
||||
x-related:
|
||||
- title: Query data
|
||||
href: /influxdb3/enterprise/query-data/
|
||||
- name: Quick start
|
||||
description: |
|
||||
1. Create an admin token to authorize API requests.
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8181/api/v3/configure/token/admin"
|
||||
```
|
||||
2. Check the status of the InfluxDB server.
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8181/health" \
|
||||
--header "Authorization: Bearer ADMIN_TOKEN"
|
||||
```
|
||||
|
||||
3. Write data to InfluxDB.
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto"
|
||||
--header "Authorization: Bearer ADMIN_TOKEN" \
|
||||
--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`.
|
||||
|
||||
4. Query data from InfluxDB.
|
||||
|
||||
```bash
|
||||
curl -G "http://localhost:8181/api/v3/query_sql" \
|
||||
--header "Authorization: Bearer ADMIN_TOKEN" \
|
||||
--data-urlencode "db=sensors" \
|
||||
--data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \
|
||||
--data-urlencode "format=jsonl"
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```jsonl
|
||||
{"room":"Living room","temp":71.5,"time":"2025-02-25T20:19:34.984098"}
|
||||
```
|
||||
|
||||
For more information, see the [Get started](/influxdb3/enterprise/get-started/) guide.
|
||||
description: Get started authenticating, writing, and querying data with the InfluxDB 3 Enterprise API.
|
||||
x-traitTag: true
|
||||
- name: Server information
|
||||
description: Retrieve server metrics, status, and version information
|
||||
description: Retrieve server metrics, health status, and version information for InfluxDB 3 Enterprise.
|
||||
- name: Table
|
||||
description: Manage table schemas and data
|
||||
description: Manage table schemas in an InfluxDB 3 Enterprise database.
|
||||
x-related:
|
||||
- title: Manage tables
|
||||
href: /influxdb3/enterprise/admin/tables/
|
||||
- name: Token
|
||||
description: Manage tokens for authentication and authorization
|
||||
description: Create and manage tokens used for authenticating and authorizing access to InfluxDB 3 Enterprise resources.
|
||||
x-related:
|
||||
- title: Manage tokens
|
||||
href: /influxdb3/enterprise/admin/tokens/
|
||||
- name: Write data
|
||||
description: |
|
||||
Write data to InfluxDB 3 Enterprise using line protocol format.
|
||||
|
||||
#### Timestamp precision across write APIs
|
||||
|
||||
InfluxDB 3 provides multiple write endpoints for compatibility with different InfluxDB versions.
|
||||
The following table compares timestamp precision support across v1, v2, and v3 write APIs:
|
||||
|
||||
| Precision | v1 (`/write`) | v2 (`/api/v2/write`) | v3 (`/api/v3/write_lp`) |
|
||||
|-----------|---------------|----------------------|-------------------------|
|
||||
| **Auto detection** | ❌ No | ❌ No | ✅ `auto` (default) |
|
||||
| **Seconds** | ✅ `s` | ✅ `s` | ✅ `second` |
|
||||
| **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `millisecond` |
|
||||
| **Microseconds** | ✅ `u` or `µ` | ✅ `us` | ✅ `microsecond` |
|
||||
| **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `nanosecond` |
|
||||
| **Minutes** | ✅ `m` | ❌ No | ❌ No |
|
||||
| **Hours** | ✅ `h` | ❌ No | ❌ No |
|
||||
| **Default** | Nanosecond | Nanosecond | **Auto** (guessed) |
|
||||
|
||||
All timestamps are stored internally as nanoseconds.
|
||||
description: Write time series data to InfluxDB 3 Enterprise in line protocol format using the v1, v2, or v3 write endpoints.
|
||||
x-related:
|
||||
- title: Write data using HTTP APIs
|
||||
href: /influxdb3/enterprise/write-data/http-api/
|
||||
- title: Line protocol reference
|
||||
href: /influxdb3/enterprise/reference/syntax/line-protocol/
|
||||
paths:
|
||||
/write:
|
||||
post:
|
||||
|
|
@ -317,7 +220,6 @@ paths:
|
|||
'413':
|
||||
description: Request entity too large.
|
||||
tags:
|
||||
|
||||
- Write data
|
||||
x-related:
|
||||
- title: Use compatibility APIs to write data
|
||||
|
|
@ -410,7 +312,6 @@ paths:
|
|||
'413':
|
||||
description: Request entity too large.
|
||||
tags:
|
||||
|
||||
- Write data
|
||||
x-related:
|
||||
- title: Use compatibility APIs to write data
|
||||
|
|
@ -835,7 +736,6 @@ paths:
|
|||
description: Unprocessable entity.
|
||||
tags:
|
||||
- Query data
|
||||
|
||||
x-related:
|
||||
- title: Use the InfluxDB v1 HTTP query API and InfluxQL to query data
|
||||
href: /influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api/
|
||||
|
|
@ -954,7 +854,6 @@ paths:
|
|||
description: Unprocessable entity.
|
||||
tags:
|
||||
- Query data
|
||||
|
||||
x-related:
|
||||
- title: Use the InfluxDB v1 HTTP query API and InfluxQL to query data
|
||||
href: /influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api/
|
||||
|
|
@ -995,7 +894,6 @@ paths:
|
|||
description: Service is unavailable.
|
||||
tags:
|
||||
- Server information
|
||||
|
||||
/ping:
|
||||
get:
|
||||
operationId: GetPing
|
||||
|
|
@ -1021,7 +919,7 @@ paths:
|
|||
description: The InfluxDB version number (for example, `3.8.0`).
|
||||
schema:
|
||||
type: string
|
||||
example: '3.8.0'
|
||||
example: 3.8.0
|
||||
x-influxdb-build:
|
||||
description: The InfluxDB build type (`Core` or `Enterprise`).
|
||||
schema:
|
||||
|
|
@ -1035,15 +933,15 @@ paths:
|
|||
version:
|
||||
type: string
|
||||
description: The InfluxDB version number.
|
||||
example: '3.8.0'
|
||||
example: 3.8.0
|
||||
revision:
|
||||
type: string
|
||||
description: The git revision hash for the build.
|
||||
example: '83b589b883'
|
||||
example: 83b589b883
|
||||
process_id:
|
||||
type: string
|
||||
description: A unique identifier for the server process.
|
||||
example: 'b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7'
|
||||
example: b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7
|
||||
'401':
|
||||
description: Unauthorized. Authentication is required.
|
||||
'404':
|
||||
|
|
@ -2,29 +2,25 @@
|
|||
/**
|
||||
* Generate OpenAPI Articles Script
|
||||
*
|
||||
* Generates Hugo data files and content pages from OpenAPI specifications
|
||||
* for all InfluxDB products.
|
||||
* Processes OpenAPI specs for Hugo-native API documentation. This script
|
||||
* expects specs to already be fetched (via getswagger.sh) and post-processed
|
||||
* (via post-process-specs.ts) before it runs.
|
||||
*
|
||||
* This script:
|
||||
* 1. Cleans output directories (unless --no-clean)
|
||||
* 2. Runs getswagger.sh to fetch/bundle OpenAPI specs
|
||||
* 3. Copies specs to static directory for download
|
||||
* 4. Generates path group fragments (YAML and JSON)
|
||||
* 5. Creates article metadata (YAML and JSON)
|
||||
* 6. Generates Hugo content pages from article data
|
||||
* Modes:
|
||||
* - Default: copy specs to static/ + generate Hugo article pages
|
||||
* - --static-only: copy specs to static/ only (no article generation)
|
||||
*
|
||||
* Usage:
|
||||
* node generate-openapi-articles.js # Clean and generate all products
|
||||
* node generate-openapi-articles.js cloud-v2 # Clean and generate single product
|
||||
* node generate-openapi-articles.js # Full generation (static + articles)
|
||||
* node generate-openapi-articles.js cloud-v2 # Single product
|
||||
* node generate-openapi-articles.js --static-only # Copy specs to static/ only
|
||||
* node generate-openapi-articles.js --no-clean # Generate without cleaning
|
||||
* node generate-openapi-articles.js --dry-run # Preview what would be cleaned
|
||||
* node generate-openapi-articles.js --skip-fetch # Skip getswagger.sh fetch step
|
||||
* node generate-openapi-articles.js --validate-links # Validate documentation links
|
||||
*
|
||||
* @module generate-openapi-articles
|
||||
*/
|
||||
|
||||
import { execSync } from 'child_process';
|
||||
import * as path from 'path';
|
||||
import * as fs from 'fs';
|
||||
|
||||
|
|
@ -90,7 +86,7 @@ const API_DOCS_ROOT = 'api-docs';
|
|||
|
||||
// CLI flags
|
||||
const validateLinks = process.argv.includes('--validate-links');
|
||||
const skipFetch = process.argv.includes('--skip-fetch');
|
||||
const staticOnly = process.argv.includes('--static-only');
|
||||
const noClean = process.argv.includes('--no-clean');
|
||||
const dryRun = process.argv.includes('--dry-run');
|
||||
|
||||
|
|
@ -142,22 +138,6 @@ const apiProductsMap = loadApiProducts();
|
|||
* @param description - Human-readable description of the command
|
||||
* @throws Exits process with code 1 on error
|
||||
*/
|
||||
function execCommand(command: string, description?: string): void {
|
||||
try {
|
||||
if (description) {
|
||||
console.log(`\n${description}...`);
|
||||
}
|
||||
console.log(`Executing: ${command}\n`);
|
||||
execSync(command, { stdio: 'inherit' });
|
||||
} catch (error) {
|
||||
console.error(`\n❌ Error executing command: ${command}`);
|
||||
if (error instanceof Error) {
|
||||
console.error(error.message);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate a clean static directory name from a product key.
|
||||
* Handles the influxdb3_* products to avoid redundant 'influxdb-influxdb3' prefixes.
|
||||
|
|
@ -945,14 +925,14 @@ const productConfigs: ProductConfigMap = {
|
|||
// InfluxDB 3 products use tag-based generation for better UX
|
||||
// Keys use underscores to match Hugo data directory structure
|
||||
influxdb3_core: {
|
||||
specFile: path.join(API_DOCS_ROOT, 'influxdb3/core/v3/influxdb3-core-openapi.yaml'),
|
||||
specFile: path.join(API_DOCS_ROOT, 'influxdb3/core/influxdb3-core-openapi.yaml'),
|
||||
pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/core'),
|
||||
description: 'InfluxDB 3 Core',
|
||||
menuKey: 'influxdb3_core',
|
||||
useTagBasedGeneration: true,
|
||||
},
|
||||
influxdb3_enterprise: {
|
||||
specFile: path.join(API_DOCS_ROOT, 'influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml'),
|
||||
specFile: path.join(API_DOCS_ROOT, 'influxdb3/enterprise/influxdb3-enterprise-openapi.yaml'),
|
||||
pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/enterprise'),
|
||||
description: 'InfluxDB 3 Enterprise',
|
||||
menuKey: 'influxdb3_enterprise',
|
||||
|
|
@ -1049,8 +1029,8 @@ const LINK_PATTERN = /\/influxdb\/version\//g;
|
|||
* Derive documentation root from spec file path.
|
||||
*
|
||||
* @example
|
||||
* 'api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml' → '/influxdb3/core'
|
||||
* 'api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml' → '/influxdb3/enterprise'
|
||||
* 'api-docs/influxdb3/core/influxdb3-core-openapi.yaml' → '/influxdb3/core'
|
||||
* 'api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml' → '/influxdb3/enterprise'
|
||||
* 'api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml' → '/influxdb/v2'
|
||||
* 'api-docs/influxdb/v1/influxdb-oss-v1-openapi.yaml' → '/influxdb/v1'
|
||||
* 'api-docs/enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml' → '/enterprise_influxdb/v1'
|
||||
|
|
@ -1316,21 +1296,6 @@ function processProduct(productKey: string, config: ProductConfig): void {
|
|||
}
|
||||
|
||||
try {
|
||||
// Step 1: Execute the getswagger.sh script to fetch/bundle the spec
|
||||
if (skipFetch) {
|
||||
console.log(`⏭️ Skipping getswagger.sh (--skip-fetch flag set)`);
|
||||
} else {
|
||||
const getswaggerScript = path.join(API_DOCS_ROOT, 'getswagger.sh');
|
||||
if (fs.existsSync(getswaggerScript)) {
|
||||
execCommand(
|
||||
`cd ${API_DOCS_ROOT} && ./getswagger.sh ${productKey} -B`,
|
||||
`Fetching OpenAPI spec for ${productKey}`
|
||||
);
|
||||
} else {
|
||||
console.log(`⚠️ getswagger.sh not found, skipping fetch step`);
|
||||
}
|
||||
}
|
||||
|
||||
// Determine spec files to process
|
||||
const specFiles: SpecFileConfig[] = config.specFiles
|
||||
? config.specFiles
|
||||
|
|
@ -1374,8 +1339,8 @@ function processProduct(productKey: string, config: ProductConfig): void {
|
|||
if (result) {
|
||||
processedSpecs.push(result);
|
||||
|
||||
// Generate tag-based article data for this spec
|
||||
if (config.useTagBasedGeneration) {
|
||||
// Generate tag-based article data for this spec (skip in --static-only mode)
|
||||
if (!staticOnly && config.useTagBasedGeneration) {
|
||||
const specSlug = specConfig.displayName
|
||||
? slugifyDisplayName(specConfig.displayName)
|
||||
: path.parse(specConfig.path).name;
|
||||
|
|
@ -1409,58 +1374,61 @@ function processProduct(productKey: string, config: ProductConfig): void {
|
|||
}
|
||||
}
|
||||
|
||||
// Step 5: Merge article data from all specs (for multi-spec products)
|
||||
if (processedSpecs.length > 1) {
|
||||
console.log(
|
||||
`\n📋 Merging article data from ${processedSpecs.length} specs...`
|
||||
);
|
||||
const articlesFiles = processedSpecs.map((s) =>
|
||||
path.join(s.articlesPath, 'articles.yml')
|
||||
);
|
||||
mergeArticleData(
|
||||
articlesFiles,
|
||||
path.join(mergedArticlesPath, 'articles.yml')
|
||||
);
|
||||
} else if (processedSpecs.length === 1) {
|
||||
// Single spec - copy articles to final location if needed
|
||||
const sourceArticles = path.join(
|
||||
processedSpecs[0].articlesPath,
|
||||
'articles.yml'
|
||||
);
|
||||
const targetArticles = path.join(mergedArticlesPath, 'articles.yml');
|
||||
|
||||
// Only copy if source and target are different
|
||||
if (sourceArticles !== targetArticles && fs.existsSync(sourceArticles)) {
|
||||
if (!fs.existsSync(mergedArticlesPath)) {
|
||||
fs.mkdirSync(mergedArticlesPath, { recursive: true });
|
||||
}
|
||||
fs.copyFileSync(sourceArticles, targetArticles);
|
||||
fs.copyFileSync(
|
||||
sourceArticles.replace('.yml', '.json'),
|
||||
targetArticles.replace('.yml', '.json')
|
||||
// Article generation (skip in --static-only mode)
|
||||
if (!staticOnly) {
|
||||
// Merge article data from all specs (for multi-spec products)
|
||||
if (processedSpecs.length > 1) {
|
||||
console.log(
|
||||
`\n📋 Merging article data from ${processedSpecs.length} specs...`
|
||||
);
|
||||
console.log(`✓ Copied article data to ${mergedArticlesPath}`);
|
||||
}
|
||||
}
|
||||
const articlesFiles = processedSpecs.map((s) =>
|
||||
path.join(s.articlesPath, 'articles.yml')
|
||||
);
|
||||
mergeArticleData(
|
||||
articlesFiles,
|
||||
path.join(mergedArticlesPath, 'articles.yml')
|
||||
);
|
||||
} else if (processedSpecs.length === 1) {
|
||||
// Single spec - copy articles to final location if needed
|
||||
const sourceArticles = path.join(
|
||||
processedSpecs[0].articlesPath,
|
||||
'articles.yml'
|
||||
);
|
||||
const targetArticles = path.join(mergedArticlesPath, 'articles.yml');
|
||||
|
||||
// Step 6: Generate Hugo content pages from (merged) article data
|
||||
if (config.useTagBasedGeneration) {
|
||||
generateTagPagesFromArticleData({
|
||||
articlesPath: mergedArticlesPath,
|
||||
contentPath: config.pagesDir,
|
||||
menuKey: config.menuKey,
|
||||
menuParent: 'InfluxDB HTTP API',
|
||||
skipParentMenu: config.skipParentMenu,
|
||||
pathSpecFiles: allPathSpecFiles,
|
||||
});
|
||||
} else {
|
||||
generatePagesFromArticleData({
|
||||
articlesPath: mergedArticlesPath,
|
||||
contentPath: config.pagesDir,
|
||||
menuKey: config.menuKey,
|
||||
menuParent: 'InfluxDB HTTP API',
|
||||
skipParentMenu: config.skipParentMenu,
|
||||
});
|
||||
// Only copy if source and target are different
|
||||
if (sourceArticles !== targetArticles && fs.existsSync(sourceArticles)) {
|
||||
if (!fs.existsSync(mergedArticlesPath)) {
|
||||
fs.mkdirSync(mergedArticlesPath, { recursive: true });
|
||||
}
|
||||
fs.copyFileSync(sourceArticles, targetArticles);
|
||||
fs.copyFileSync(
|
||||
sourceArticles.replace('.yml', '.json'),
|
||||
targetArticles.replace('.yml', '.json')
|
||||
);
|
||||
console.log(`✓ Copied article data to ${mergedArticlesPath}`);
|
||||
}
|
||||
}
|
||||
|
||||
// Generate Hugo content pages from (merged) article data
|
||||
if (config.useTagBasedGeneration) {
|
||||
generateTagPagesFromArticleData({
|
||||
articlesPath: mergedArticlesPath,
|
||||
contentPath: config.pagesDir,
|
||||
menuKey: config.menuKey,
|
||||
menuParent: 'InfluxDB HTTP API',
|
||||
skipParentMenu: config.skipParentMenu,
|
||||
pathSpecFiles: allPathSpecFiles,
|
||||
});
|
||||
} else {
|
||||
generatePagesFromArticleData({
|
||||
articlesPath: mergedArticlesPath,
|
||||
contentPath: config.pagesDir,
|
||||
menuKey: config.menuKey,
|
||||
menuParent: 'InfluxDB HTTP API',
|
||||
skipParentMenu: config.skipParentMenu,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
console.log(
|
||||
|
|
|
|||
|
|
@ -1,76 +1,18 @@
|
|||
---
|
||||
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
|
||||
|
||||
```
|
||||
Authenticate API requests to InfluxDB Enterprise v1 using basic
|
||||
authentication, query string credentials, or the v2-compatible token scheme.
|
||||
type: api
|
||||
layout: single
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-authentication.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-openapi-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
|
||||
|
||||
```
|
||||
Authenticate API requests to InfluxDB Enterprise v1 using basic
|
||||
authentication, query string credentials, or the v2-compatible token scheme.
|
||||
showSecuritySchemes: true
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
---
|
||||
title: Debug
|
||||
description: >-
|
||||
Debugging and profiling endpoints for troubleshooting and performance
|
||||
analysis.
|
||||
Access debugging and profiling endpoints for troubleshooting and performance
|
||||
analysis of an InfluxDB Enterprise v1 instance.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-debug.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-openapi-debug.yaml
|
||||
weight: 100
|
||||
tag: Debug
|
||||
isConceptual: false
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
---
|
||||
title: Query
|
||||
description: |-
|
||||
Query data using InfluxQL. The `/query` endpoint supports both read queries
|
||||
(SELECT, SHOW) and write queries (CREATE, DROP, ALTER, etc.).
|
||||
description: >-
|
||||
Query data using InfluxQL via the `/query` endpoint, supporting both read
|
||||
queries (SELECT, SHOW) and management queries (CREATE, DROP, ALTER).
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-query.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-openapi-query.yaml
|
||||
weight: 100
|
||||
tag: Query
|
||||
isConceptual: false
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
---
|
||||
title: System Information
|
||||
description: Endpoints for checking server status, health, and version information.
|
||||
description: >-
|
||||
Check server status, health, and version information for an InfluxDB
|
||||
Enterprise v1 instance.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-system-information.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-openapi-system-information.yaml
|
||||
weight: 100
|
||||
tag: System Information
|
||||
isConceptual: false
|
||||
|
|
|
|||
|
|
@ -1,17 +1,13 @@
|
|||
---
|
||||
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
|
||||
```
|
||||
description: >-
|
||||
InfluxDB v2-compatible API endpoints that allow InfluxDB 2.x client libraries
|
||||
to work with InfluxDB Enterprise 1.8+, using the Token authentication scheme
|
||||
with v1 credentials.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-v2-compatibility.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-openapi-v2-compatibility.yaml
|
||||
weight: 100
|
||||
tag: v2 Compatibility
|
||||
isConceptual: false
|
||||
|
|
|
|||
|
|
@ -1,17 +1,13 @@
|
|||
---
|
||||
title: Write
|
||||
description: >-
|
||||
Write time series data using InfluxDB line protocol.
|
||||
|
||||
|
||||
**Enterprise Feature**: Use the `consistency` parameter to control write
|
||||
consistency
|
||||
|
||||
across cluster nodes.
|
||||
Write time series data to InfluxDB Enterprise v1 in line protocol format using
|
||||
the `/write` endpoint. Use the `consistency` parameter to control write
|
||||
consistency across cluster nodes.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-write.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-openapi-write.yaml
|
||||
weight: 100
|
||||
tag: Write
|
||||
isConceptual: false
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# API Docs Uplift — Branch Extraction and Tag Cleanup
|
||||
|
||||
**Status:** Implementation in progress — pending commit, push, and PR.
|
||||
**Status:** Implementation complete — pushed to `origin/api-docs-uplift`, pending PR.
|
||||
|
||||
## Goal
|
||||
|
||||
Extract all `api-docs/` changes from `feat-api-uplift` into a standalone PR (`api-docs-uplift`) that ships independently to master. Clean up tag structures, add descriptions and `x-related` links, remove dead `x-tagGroups` infrastructure, relabel v2-compat spec directories, introduce a unified spec post-processor, and migrate inline spec links to `tags.yml`.
|
||||
Extract all `api-docs/` changes from `feat-api-uplift` into a standalone PR (`api-docs-uplift`) that ships independently to master. Clean up tag structures, add descriptions and `x-related` links, remove dead `x-tagGroups` infrastructure, flatten all version subdirectories to a uniform layout, remove redundant v1-compatibility specs, introduce a unified spec post-processor, and migrate inline spec links to `tags.yml`.
|
||||
|
||||
***
|
||||
|
||||
|
|
@ -26,6 +26,9 @@ Extract all `api-docs/` changes from `feat-api-uplift` into a standalone PR (`ap
|
|||
12. ✅ Fix `generate-api-docs.sh` info.yml resolution for flattened directories
|
||||
13. ✅ Wire `post-process-specs.ts` into `generate-api-docs.sh` pipeline
|
||||
14. ✅ Fix doubled `static/openapi/` download filenames
|
||||
15. ✅ Unify v2 APIs: flatten `influxdb/cloud/v2/` and `influxdb/v2/v2/` to product root
|
||||
16. ✅ Remove all v1-compatibility specs and directories (5 products)
|
||||
17. ✅ Flatten v3 directories for Core and Enterprise
|
||||
|
||||
**Out of scope (deferred):**
|
||||
|
||||
|
|
@ -60,65 +63,72 @@ feat-api-uplift ─── merge master ─── merge #6907│
|
|||
7. ✅ Flatten version subdirectories for v2-compat and v1 — commit `abc789013`
|
||||
8. ✅ Fix docs-tooling spec passthrough for Core/Enterprise — commit `58b706deb`
|
||||
9. ✅ Replace tag-only processor with unified post-process-specs — commit `c7f9353d0`
|
||||
10. 🔲 Migrate management spec links, fix build pipeline, fix download names — pending commit
|
||||
11. 🔲 Push to `origin/api-docs-uplift`
|
||||
12. 🔲 Open PR, merge to master
|
||||
13. 🔲 Rebase `feat-api-uplift` onto updated master
|
||||
10. ✅ Migrate management spec links, unify v2 APIs, remove v1-compat specs, fix build pipeline, fix download names — commit `24c1e60f2`
|
||||
11. ✅ Merge `origin/master` into `api-docs-uplift` — commit `160b308af`
|
||||
12. ✅ Flatten v3 directories for Core and Enterprise — pending commit
|
||||
13. ✅ Push to `origin/api-docs-uplift`
|
||||
14. 🔲 Open PR, merge to master
|
||||
15. 🔲 Rebase `feat-api-uplift` onto updated master
|
||||
|
||||
***
|
||||
|
||||
## Directory Relabeling
|
||||
## Directory Flattening
|
||||
|
||||
Drop redundant version subdirectories and use self-documenting filenames. Applies to v2-compat influxdb3 products and v1 products.
|
||||
Drop all redundant version subdirectories. Every product now stores its spec, `tags.yml`, and `content/` at the product root with a self-documenting filename. This applies to all product categories.
|
||||
|
||||
### v2-compat influxdb3 products
|
||||
|
||||
These products store specs under a `v2/` subdirectory. They have a single data API — the version directory is misleading and implies parity with the full InfluxDB v2 API.
|
||||
|
||||
#### Before
|
||||
|
||||
```
|
||||
api-docs/influxdb3/cloud-dedicated/v2/ref.yml
|
||||
api-docs/influxdb3/cloud-serverless/v2/ref.yml
|
||||
api-docs/influxdb3/clustered/v2/ref.yml
|
||||
```
|
||||
|
||||
#### After
|
||||
### Final layout (all products)
|
||||
|
||||
```
|
||||
api-docs/influxdb3/core/influxdb3-core-openapi.yaml
|
||||
api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml
|
||||
api-docs/influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml
|
||||
api-docs/influxdb3/cloud-dedicated/management/openapi.yml
|
||||
api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml
|
||||
api-docs/influxdb3/clustered/influxdb3-clustered-openapi.yaml
|
||||
```
|
||||
|
||||
### v1 products
|
||||
|
||||
Same redundancy: `influxdb/v1/v1/ref.yml` — the inner `v1/` adds nothing. The v1 API surface is small (~14 endpoints) and the v2-compat endpoints are a natural subset already tagged `v2 Compatibility`. Single spec, flattened directory.
|
||||
|
||||
#### Before
|
||||
|
||||
```
|
||||
api-docs/influxdb/v1/v1/ref.yml
|
||||
api-docs/enterprise_influxdb/v1/v1/ref.yml
|
||||
```
|
||||
|
||||
#### After
|
||||
|
||||
```
|
||||
api-docs/influxdb3/clustered/management/openapi.yml
|
||||
api-docs/influxdb/cloud/influxdb-cloud-v2-openapi.yaml
|
||||
api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml
|
||||
api-docs/influxdb/v1/influxdb-oss-v1-openapi.yaml
|
||||
api-docs/enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml
|
||||
```
|
||||
|
||||
### Files to update per product
|
||||
### Directories removed
|
||||
|
||||
| Old path | Reason |
|
||||
| --- | --- |
|
||||
| `influxdb3/core/v3/` | Single API — `v3/` nesting is redundant |
|
||||
| `influxdb3/enterprise/v3/` | Same |
|
||||
| `influxdb3/cloud-dedicated/v2/` | Single data API — `v2/` implies parity with full v2 API |
|
||||
| `influxdb3/cloud-serverless/v2/` | Same |
|
||||
| `influxdb3/clustered/v2/` | Same |
|
||||
| `influxdb/cloud/v2/` | Single API — flattened to product root |
|
||||
| `influxdb/v2/v2/` | Same (`v2/v2/` was doubly nested) |
|
||||
| `influxdb/v1/v1/` | Same (`v1/v1/`) |
|
||||
| `enterprise_influxdb/v1/v1/` | Same |
|
||||
|
||||
### v1-compatibility removal
|
||||
|
||||
All 5 `v1-compatibility/` directories were deleted. The v1-compatible endpoints (query, write, auth) are already included in the main spec for each product, tagged as "v1 Compatibility" or similar. Separate specs were redundant.
|
||||
|
||||
| Deleted directory | Product |
|
||||
| --- | --- |
|
||||
| `influxdb/cloud/v1-compatibility/` | Cloud v2 |
|
||||
| `influxdb/v2/v1-compatibility/` | OSS v2 |
|
||||
| `influxdb3/cloud-dedicated/v1-compatibility/` | Cloud Dedicated |
|
||||
| `influxdb3/cloud-serverless/v1-compatibility/` | Cloud Serverless |
|
||||
| `influxdb3/clustered/v1-compatibility/` | Clustered |
|
||||
|
||||
Old v1-compatibility URLs are preserved as Hugo aliases in each product's `.config.yml`.
|
||||
|
||||
### Files updated per product
|
||||
|
||||
| File | Change |
|
||||
| --- | --- |
|
||||
| `{product}/.config.yml` | Update `apis` key and `root:` path |
|
||||
| `{product}/` | Move spec + content + tags.yml, delete empty version subdirectory |
|
||||
| `api-docs/getswagger.sh` | Update `outFile` path in fetch functions |
|
||||
| `api-docs/generate-api-docs.sh` | Fix info.yml resolution for flattened paths |
|
||||
| `{product}/.config.yml` | Update `root:` path, remove v1-compat API entries, add alias redirects |
|
||||
| `api-docs/getswagger.sh` | Update `outFile` paths, remove `updateV1Compat` function |
|
||||
| `api-docs/scripts/generate-openapi-articles.ts` | Update spec paths |
|
||||
|
||||
Management API specs (`management/openapi.yml`) already use this pattern and need no changes.
|
||||
Management API specs (`management/openapi.yml`) already used this pattern and needed no changes.
|
||||
|
||||
***
|
||||
|
||||
|
|
@ -204,7 +214,7 @@ tags:
|
|||
### Discovery convention
|
||||
|
||||
```
|
||||
api-docs/influxdb3/core/v3/
|
||||
api-docs/influxdb3/core/
|
||||
├── influxdb3-core-openapi.yaml # spec file
|
||||
├── tags.yml # tag config
|
||||
└── content/
|
||||
|
|
@ -325,16 +335,16 @@ fi
|
|||
|
||||
## Products to Adapt
|
||||
|
||||
### v3 native (tags already done, extract to `tags.yml`)
|
||||
### v3 native (tags done)
|
||||
|
||||
| Product | Spec | Work |
|
||||
| Product | Spec | Status |
|
||||
| --- | --- | --- |
|
||||
| Core | `influxdb3/core/v3/influxdb3-core-openapi.yaml` | Extract existing tags to `tags.yml` |
|
||||
| Enterprise | `influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml` | Extract existing tags to `tags.yml` |
|
||||
| Core | `influxdb3/core/influxdb3-core-openapi.yaml` | ✅ Tags, descriptions, `x-related` in `tags.yml` |
|
||||
| Enterprise | `influxdb3/enterprise/influxdb3-enterprise-openapi.yaml` | ✅ Tags, descriptions, `x-related` in `tags.yml` |
|
||||
|
||||
### v2-compat (need tag review + descriptions + `x-related`)
|
||||
### v2-compat
|
||||
|
||||
| Product | Spec (after relabel) | Work |
|
||||
| Product | Spec | Status |
|
||||
| --- | --- | --- |
|
||||
| Cloud Dedicated (data) | `influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml` | Review tags, add descriptions, add `x-related` |
|
||||
| Cloud Dedicated (mgmt) | `influxdb3/cloud-dedicated/management/openapi.yml` | ✅ Tags, descriptions, `x-related`, inline link migration |
|
||||
|
|
@ -344,14 +354,14 @@ fi
|
|||
|
||||
### v2 full
|
||||
|
||||
| Product | Spec | Work |
|
||||
| Product | Spec | Status |
|
||||
| --- | --- | --- |
|
||||
| Cloud v2 | `influxdb/cloud/v2/ref.yml` | Review tags, add descriptions |
|
||||
| OSS v2 | `influxdb/v2/v2/ref.yml` | Review tags, add descriptions |
|
||||
| Cloud v2 | `influxdb/cloud/influxdb-cloud-v2-openapi.yaml` | Review tags, add descriptions |
|
||||
| OSS v2 | `influxdb/v2/influxdb-oss-v2-openapi.yaml` | Review tags, add descriptions |
|
||||
|
||||
### v1
|
||||
|
||||
| Product | Spec | Work |
|
||||
| Product | Spec | Status |
|
||||
| --- | --- | --- |
|
||||
| OSS v1 | `influxdb/v1/influxdb-oss-v1-openapi.yaml` | Review tags, add descriptions |
|
||||
| Enterprise v1 | `enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml` | Review tags, add descriptions |
|
||||
|
|
@ -366,15 +376,15 @@ fi
|
|||
| --- | --- |
|
||||
| `api-docs/scripts/post-process-specs.ts` | Unified spec post-processor (info, servers, tags) |
|
||||
| `api-docs/scripts/test-post-process-specs.ts` | 13 tests, 41 assertions |
|
||||
| `api-docs/influxdb3/core/v3/tags.yml` | Core tag config |
|
||||
| `api-docs/influxdb3/enterprise/v3/tags.yml` | Enterprise tag config |
|
||||
| `api-docs/influxdb3/core/tags.yml` | Core tag config |
|
||||
| `api-docs/influxdb3/enterprise/tags.yml` | Enterprise tag config |
|
||||
| `api-docs/influxdb3/cloud-dedicated/tags.yml` | Cloud Dedicated data API tag config |
|
||||
| `api-docs/influxdb3/cloud-dedicated/management/tags.yml` | Cloud Dedicated management tag config |
|
||||
| `api-docs/influxdb3/cloud-serverless/tags.yml` | Cloud Serverless tag config |
|
||||
| `api-docs/influxdb3/clustered/tags.yml` | Clustered data API tag config |
|
||||
| `api-docs/influxdb3/clustered/management/tags.yml` | Clustered management tag config |
|
||||
| `api-docs/influxdb/cloud/v2/tags.yml` | Cloud v2 tag config |
|
||||
| `api-docs/influxdb/v2/v2/tags.yml` | OSS v2 tag config |
|
||||
| `api-docs/influxdb/cloud/tags.yml` | Cloud v2 tag config |
|
||||
| `api-docs/influxdb/v2/tags.yml` | OSS v2 tag config |
|
||||
| `api-docs/influxdb/v1/tags.yml` | OSS v1 tag config |
|
||||
| `api-docs/enterprise_influxdb/v1/tags.yml` | Enterprise v1 tag config |
|
||||
|
||||
|
|
@ -383,7 +393,11 @@ fi
|
|||
| File | Change |
|
||||
| --- | --- |
|
||||
| `api-docs/generate-api-docs.sh` | Fix info.yml resolution; wire post-process-specs.ts into pipeline |
|
||||
| `api-docs/getswagger.sh` | Update `outFile` paths; skip Redocly for management specs |
|
||||
| `api-docs/getswagger.sh` | Update `outFile` paths; skip Redocly for management specs; remove `updateV1Compat` |
|
||||
| `api-docs/influxdb/cloud/.config.yml` | Flatten `root:` path, remove v1-compat API entry, add alias redirects |
|
||||
| `api-docs/influxdb/v2/.config.yml` | Flatten `root:` path |
|
||||
| `api-docs/influxdb3/core/.config.yml` | Flatten `root:` path |
|
||||
| `api-docs/influxdb3/enterprise/.config.yml` | Flatten `root:` path |
|
||||
| `api-docs/openapi/plugins/docs-plugin.cjs` | Remove `set-tag-groups` decorator |
|
||||
| `api-docs/influxdb3/cloud-dedicated/.config.yml` | Update API key, spec root path, restore `management@0` |
|
||||
| `api-docs/influxdb3/cloud-serverless/.config.yml` | Update API key and spec root path |
|
||||
|
|
@ -402,11 +416,16 @@ fi
|
|||
| `api-docs/scripts/test-apply-tag-config.ts` | Replaced by `test-post-process-specs.ts` |
|
||||
| `api-docs/openapi/plugins/decorators/tags/set-tag-groups.cjs` | Dead — `x-tagGroups` removed |
|
||||
| 10 `content/tag-groups.yml` files | Dead configs |
|
||||
| `api-docs/influxdb3/cloud-dedicated/v2/` | Replaced by relabeled spec at product root |
|
||||
| `api-docs/influxdb3/cloud-serverless/v2/` | Replaced by relabeled spec at product root |
|
||||
| `api-docs/influxdb3/clustered/v2/` | Replaced by relabeled spec at product root |
|
||||
| `api-docs/influxdb/v1/v1/` | Replaced by relabeled spec at product root |
|
||||
| `api-docs/enterprise_influxdb/v1/v1/` | Replaced by relabeled spec at product root |
|
||||
| `api-docs/influxdb3/core/v3/` | Flattened to product root |
|
||||
| `api-docs/influxdb3/enterprise/v3/` | Flattened to product root |
|
||||
| `api-docs/influxdb3/cloud-dedicated/v2/` | Flattened to product root |
|
||||
| `api-docs/influxdb3/cloud-serverless/v2/` | Flattened to product root |
|
||||
| `api-docs/influxdb3/clustered/v2/` | Flattened to product root |
|
||||
| `api-docs/influxdb/cloud/v2/` | Flattened to product root |
|
||||
| `api-docs/influxdb/v2/v2/` | Flattened to product root |
|
||||
| `api-docs/influxdb/v1/v1/` | Flattened to product root |
|
||||
| `api-docs/enterprise_influxdb/v1/v1/` | Flattened to product root |
|
||||
| 5 `v1-compatibility/` directories | Redundant — endpoints already in main spec |
|
||||
|
||||
***
|
||||
|
||||
|
|
@ -417,11 +436,12 @@ fi
|
|||
3. Spot-check generated tag pages for each product — tag names, descriptions, and `x-related` links render
|
||||
4. Verify `x-tagGroups` is absent from all specs: `grep -r 'x-tagGroups' api-docs/ --include='*.yml' --include='*.yaml'`
|
||||
5. Verify no stale `tag-groups.yml` files: `find api-docs/ -name 'tag-groups.yml'`
|
||||
6. Verify relabeled specs: `ls api-docs/influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml`
|
||||
7. Verify v1 relabeled specs: `ls api-docs/influxdb/v1/influxdb-oss-v1-openapi.yaml api-docs/enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml`
|
||||
8. Verify no markdown links in management specs: `grep -c '\[.*\](/' api-docs/influxdb3/*/management/openapi.yml`
|
||||
9. Verify download filenames in `static/openapi/` — no doubled product names
|
||||
10. Verify post-process-specs tests: `node api-docs/scripts/dist/test-post-process-specs.js`
|
||||
6. Verify no version subdirectories: `find api-docs -maxdepth 4 -name 'v2' -o -name 'v3' | grep -v node_modules`
|
||||
7. Verify all specs at product root: `ls api-docs/influxdb3/core/influxdb3-core-openapi.yaml api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml api-docs/influxdb/cloud/influxdb-cloud-v2-openapi.yaml api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml`
|
||||
8. Verify no v1-compat directories: `find api-docs -name 'v1-compatibility' -type d`
|
||||
9. Verify no markdown links in management specs: `grep -c '\[.*\](/' api-docs/influxdb3/*/management/openapi.yml`
|
||||
10. Verify download filenames in `static/openapi/` — no doubled product names
|
||||
11. Verify post-process-specs tests: `node api-docs/scripts/dist/test-post-process-specs.js`
|
||||
|
||||
***
|
||||
|
||||
|
|
@ -476,14 +496,29 @@ Removed `title`, `version`, `description`, `license`, `contact` from Core and En
|
|||
- Restored `management@0` API entries in `cloud-dedicated/.config.yml` and `clustered/.config.yml`.
|
||||
- 13 tests, 41 assertions, all passing.
|
||||
|
||||
### Pending commit — Migrate management links, fix build pipeline, fix download names
|
||||
### Commit 7: `24c1e60f2` — Unify v2 APIs, remove v1-compat specs, migrate mgmt links
|
||||
|
||||
- Migrated all inline markdown links from management spec descriptions to `tags.yml` `x-related` fields (Cloud Dedicated + Clustered).
|
||||
- Fixed `generate-api-docs.sh` info.yml resolution: uses spec directory first, product directory fallback (matches `post-process-specs.ts` convention).
|
||||
- Flattened Cloud v2 (`influxdb/cloud/v2/ref.yml` → `influxdb/cloud/influxdb-cloud-v2-openapi.yaml`) and OSS v2 (`influxdb/v2/v2/ref.yml` → `influxdb/v2/influxdb-oss-v2-openapi.yaml`) to product root.
|
||||
- Deleted all 5 `v1-compatibility/` directories (10 files) — endpoints already in main specs.
|
||||
- Old v1-compat URLs preserved as Hugo aliases in `.config.yml`.
|
||||
- Removed `updateV1Compat` function and `v1-compat` subcommand from `getswagger.sh`.
|
||||
- Migrated inline markdown links from management spec descriptions to `tags.yml` `x-related` fields (Cloud Dedicated + Clustered).
|
||||
- Fixed `generate-api-docs.sh` info.yml resolution: spec directory first, product directory fallback.
|
||||
- Wired `post-process-specs.ts` into `generate-api-docs.sh` pipeline between Redocly bundling and article generation.
|
||||
- Fixed doubled `static/openapi/` download filenames by stripping `staticDirName` prefix from spec filenames.
|
||||
- Fixed doubled `static/openapi/` download filenames by stripping `staticDirName` prefix.
|
||||
- Converted single-spec products (`cloud-v2`, `oss-v2`, `cloud-serverless`) to `specFiles` with `displayName` for clean download names.
|
||||
|
||||
### Commit 8: `160b308af` — Merge origin/master
|
||||
|
||||
Merged latest `origin/master` to pick up Telegraf plugin updates, label infrastructure, doc review workflows, and other changes.
|
||||
|
||||
### Pending commit — Flatten v3 directories for Core and Enterprise
|
||||
|
||||
- Moved `influxdb3/core/v3/` contents to `influxdb3/core/` (spec, tags.yml, content/).
|
||||
- Moved `influxdb3/enterprise/v3/` contents to `influxdb3/enterprise/` (spec, tags.yml, content/).
|
||||
- Updated `.config.yml` root paths, `getswagger.sh` outFile paths, `generate-openapi-articles.ts` spec paths.
|
||||
- No version subdirectories remain anywhere in `api-docs/`.
|
||||
|
||||
***
|
||||
|
||||
## Incremental Redocly Removal Plan
|
||||
|
|
|
|||
Loading…
Reference in New Issue