refactor(api-docs): unify v2 APIs, remove v1-compat specs, migrate mgmt links
Flatten Cloud v2 and OSS v2 spec directories to product root with self-documenting filenames, matching the pattern used for influxdb3 products. Remove all 5 v1-compatibility directories — those endpoints are already included in the main spec (tagged as v1/v2 Compatibility). Old v1-compat URLs are preserved as Hugo aliases for redirects. Also includes: - Migrate inline markdown links from management API spec descriptions into tags.yml x-related fields (Cloud Dedicated + Clustered) - Wire post-process-specs.ts into generate-api-docs.sh build pipeline - Fix doubled static/openapi download filenames - Update project plan with design decisionspull/6942/head
Jason Stirnaman
parent
c7f9353d0a
commit
24c1e60f2f
|
|
@ -51,11 +51,21 @@ function generateHtml {
|
|||
local apiName=$(echo $api | sed 's/@.*//g;')
|
||||
# Extract the API version--for example, "v0" from "management@v0".
|
||||
local apiVersion=$(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"
|
||||
fi
|
||||
|
||||
# Use the title and summary defined in the product API's info.yml file.
|
||||
local title=$(yq '.title' $productVersion/$apiName/content/info.yml)
|
||||
local menuTitle=$(yq '.x-influxdata-short-title' $productVersion/$apiName/content/info.yml)
|
||||
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' $productVersion/$apiName/content/info.yml)
|
||||
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.
|
||||
|
|
@ -188,7 +198,13 @@ function build {
|
|||
|
||||
build
|
||||
|
||||
# Generate tag-based article data and content pages
|
||||
# Apply content overlays (info, servers) and tag configs to bundled specs
|
||||
echo "Post-processing specs..."
|
||||
cd ..
|
||||
node api-docs/scripts/dist/post-process-specs.js
|
||||
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
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
# Use this script to retrieve the following InfluxData API specifications:
|
||||
# - the latest, fully resolved openapi (OAS, OpenAPI Specification) contract files from the influxdata/openapi repo
|
||||
#
|
||||
# Specify a product to retrieve (cloud-serverless, cloud-dedicated, clustered, cloud, v2, v1-compatibility, all).
|
||||
# Specify a product to retrieve (cloud-serverless, cloud-dedicated, clustered, cloud, v2, all).
|
||||
# Optionally specify:
|
||||
# - an OSS version as the second argument or using the -o flag.
|
||||
# The version specifies where to write the updated openapi.
|
||||
|
|
@ -62,7 +62,7 @@ function showHelp {
|
|||
subcommand=$1
|
||||
|
||||
case "$subcommand" in
|
||||
cloud-dedicated-v2|cloud-dedicated-management|cloud-serverless-v2|clustered-management|clustered-v2|cloud-v2|v2|v1-compat|oss-v1|enterprise-v1|core-v3|enterprise-v3|all)
|
||||
cloud-dedicated-v2|cloud-dedicated-management|cloud-serverless-v2|clustered-management|clustered-v2|cloud-v2|v2|oss-v1|enterprise-v1|core-v3|enterprise-v3|all)
|
||||
product=$1
|
||||
shift
|
||||
|
||||
|
|
@ -139,7 +139,7 @@ function postProcess() {
|
|||
}
|
||||
|
||||
function updateCloudV2 {
|
||||
outFile="influxdb/cloud/v2/ref.yml"
|
||||
outFile="influxdb/cloud/influxdb-cloud-v2-openapi.yaml"
|
||||
if [[ -z "$baseUrl" ]];
|
||||
then
|
||||
echo "Using existing $outFile"
|
||||
|
|
@ -241,7 +241,7 @@ function updateEnterpriseV3 {
|
|||
}
|
||||
|
||||
function updateOSSV2 {
|
||||
outFile="influxdb/v2/v2/ref.yml"
|
||||
outFile="influxdb/v2/influxdb-oss-v2-openapi.yaml"
|
||||
if [[ -z "$baseUrlOSS" ]];
|
||||
then
|
||||
echo "Using existing $outFile"
|
||||
|
|
@ -251,30 +251,6 @@ function updateOSSV2 {
|
|||
postProcess $outFile 'influxdb/v2/.config.yml' 'v2@2'
|
||||
}
|
||||
|
||||
function updateV1Compat {
|
||||
outFile="influxdb/cloud/v1-compatibility/swaggerV1Compat.yml"
|
||||
if [[ -z "$baseUrl" ]];
|
||||
then
|
||||
echo "Using existing $outFile"
|
||||
else
|
||||
curl $UPDATE_OPTIONS ${baseUrl}/contracts/swaggerV1Compat.yml -o $outFile
|
||||
fi
|
||||
postProcess $outFile 'influxdb/cloud/.config.yml' 'v1-compatibility'
|
||||
|
||||
outFile="influxdb/v2/v1-compatibility/swaggerV1Compat.yml"
|
||||
cp influxdb/cloud/v1-compatibility/swaggerV1Compat.yml $outFile
|
||||
postProcess $outFile 'influxdb/v2/.config.yml' 'v1-compatibility'
|
||||
|
||||
outFile="influxdb3/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml"
|
||||
postProcess $outFile 'influxdb3/cloud-dedicated/.config.yml' 'v1-compatibility'
|
||||
|
||||
outFile="influxdb3/cloud-serverless/v1-compatibility/swaggerV1Compat.yml"
|
||||
postProcess $outFile 'influxdb3/cloud-serverless/.config.yml' 'v1-compatibility'
|
||||
|
||||
outFile="influxdb3/clustered/v1-compatibility/swaggerV1Compat.yml"
|
||||
postProcess $outFile 'influxdb3/clustered/.config.yml' 'v1-compatibility'
|
||||
}
|
||||
|
||||
function updateOSSV1 {
|
||||
outFile="influxdb/v1/influxdb-oss-v1-openapi.yaml"
|
||||
echo "Processing $outFile with decorators"
|
||||
|
|
@ -323,9 +299,6 @@ then
|
|||
elif [ "$product" = "v2" ];
|
||||
then
|
||||
updateOSSV2
|
||||
elif [ "$product" = "v1-compat" ];
|
||||
then
|
||||
updateV1Compat
|
||||
elif [ "$product" = "oss-v1" ];
|
||||
then
|
||||
updateOSSV1
|
||||
|
|
@ -344,8 +317,7 @@ then
|
|||
updateOSSV2
|
||||
updateOSSV1
|
||||
updateEnterpriseV1
|
||||
updateV1Compat
|
||||
else
|
||||
echo "Provide a product argument: cloud-v2, cloud-serverless-v2, cloud-dedicated-v2, cloud-dedicated-management, clustered-management, clustered-v2, core-v3, enterprise-v3, v2, oss-v1, enterprise-v1, v1-compat, or all."
|
||||
echo "Provide a product argument: cloud-v2, cloud-serverless-v2, cloud-dedicated-v2, cloud-dedicated-management, clustered-management, clustered-v2, core-v3, enterprise-v3, v2, oss-v1, enterprise-v1, or all."
|
||||
showHelp
|
||||
fi
|
||||
|
|
|
|||
|
|
@ -7,10 +7,8 @@ x-influxdata-product-name: InfluxDB v2 Cloud
|
|||
|
||||
apis:
|
||||
v2@2:
|
||||
root: v2/ref.yml
|
||||
root: influxdb-cloud-v2-openapi.yaml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb/cloud/api/
|
||||
v1-compatibility@2:
|
||||
root: v1-compatibility/swaggerV1Compat.yml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb/cloud/api/v1/
|
||||
- /influxdb/cloud/api/v1-compatibility/
|
||||
|
|
|
|||
|
|
@ -1,17 +0,0 @@
|
|||
title: InfluxDB v1 HTTP API for InfluxDB Cloud (TSM)
|
||||
x-influxdata-short-title: v1 Compatibility API
|
||||
x-influxdata-short-description: The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB v2 bucket using InfluxDB v1 endpoints.
|
||||
description: |
|
||||
The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB v2 bucket using InfluxDB v1 endpoints.
|
||||
|
||||
The `/write` and `/query` endpoints support InfluxDB 1.x client libraries and third-party integrations such as Grafana.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
license:
|
||||
name: MIT
|
||||
url: 'https://opensource.org/licenses/MIT'
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
|
|
@ -1,470 +0,0 @@
|
|||
openapi: 3.0.0
|
||||
info:
|
||||
title: InfluxDB v1 HTTP API for InfluxDB Cloud (TSM)
|
||||
version: ''
|
||||
description: |
|
||||
The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB v2 bucket using InfluxDB v1 endpoints.
|
||||
|
||||
The `/write` and `/query` endpoints support InfluxDB 1.x client libraries and third-party integrations such as Grafana.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
servers:
|
||||
- url: /
|
||||
security:
|
||||
- TokenAuthentication: []
|
||||
- BasicAuthentication: []
|
||||
- QuerystringAuthentication: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: |
|
||||
The InfluxDB 1.x API requires authentication for all requests.
|
||||
InfluxDB Cloud uses InfluxDB API tokens to authenticate requests.
|
||||
|
||||
|
||||
For more information, see the following:
|
||||
- [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
x-traitTag: true
|
||||
- name: Query
|
||||
- name: Write
|
||||
paths:
|
||||
/write:
|
||||
post:
|
||||
operationId: PostWriteV1
|
||||
tags:
|
||||
- Write
|
||||
summary: Write time series data into InfluxDB in a V1-compatible format
|
||||
requestBody:
|
||||
description: Line protocol body
|
||||
required: true
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy.
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: precision
|
||||
schema:
|
||||
type: string
|
||||
description: Write precision.
|
||||
- in: header
|
||||
name: Content-Encoding
|
||||
description: When present, its value indicates to the database that compression is applied to the line protocol body.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
responses:
|
||||
'204':
|
||||
description: Write data is correctly formatted and accepted for writing to the bucket.
|
||||
'400':
|
||||
description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolError'
|
||||
'401':
|
||||
description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'403':
|
||||
description: No token was sent and they are required.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'413':
|
||||
description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolLengthError'
|
||||
'429':
|
||||
description: Token is temporarily over quota. The Retry-After header describes when to try the write again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
'503':
|
||||
description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
default:
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/query:
|
||||
post:
|
||||
operationId: PostQueryV1
|
||||
tags:
|
||||
- Query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
requestBody:
|
||||
description: InfluxQL query to execute.
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: header
|
||||
name: Accept
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
||||
default: application/json
|
||||
enum:
|
||||
- application/json
|
||||
- application/csv
|
||||
- text/csv
|
||||
- application/x-msgpack
|
||||
- in: header
|
||||
name: Accept-Encoding
|
||||
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
- in: header
|
||||
name: Content-Type
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- application/vnd.influxql
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: Bucket to query.
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: q
|
||||
description: Defines the influxql query to run.
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Query results
|
||||
headers:
|
||||
Content-Encoding:
|
||||
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
Trace-Id:
|
||||
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies the request's trace ID.
|
||||
content:
|
||||
application/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
text/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLResponse'
|
||||
examples:
|
||||
influxql-chunk_size_2:
|
||||
value: |
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
|
||||
application/x-msgpack:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'429':
|
||||
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
default:
|
||||
description: Error processing query
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
components:
|
||||
parameters:
|
||||
TraceSpan:
|
||||
in: header
|
||||
name: Zap-Trace-Span
|
||||
description: OpenTracing span context
|
||||
example:
|
||||
trace_id: '1'
|
||||
span_id: '1'
|
||||
baggage:
|
||||
key: value
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
AuthUserV1:
|
||||
in: query
|
||||
name: u
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: Username.
|
||||
AuthPassV1:
|
||||
in: query
|
||||
name: p
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: User token.
|
||||
schemas:
|
||||
InfluxQLResponse:
|
||||
description: |
|
||||
The JSON response for an InfluxQL query.
|
||||
|
||||
A response contains the collection of results for a query.
|
||||
`results` is an array of resultset objects.
|
||||
|
||||
If the response is chunked, the `transfer-encoding` response header is set to `chunked` and each resultset object is sent in a separate JSON object.
|
||||
properties:
|
||||
results:
|
||||
description: |
|
||||
A resultset object that contains the `statement_id` and the `series` array.
|
||||
|
||||
Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the resultset is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
series:
|
||||
description: |
|
||||
An array of series objects--the results of the query. A series of rows shares the same group key returned from the execution of a statement.
|
||||
|
||||
If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
columns:
|
||||
description: An array of column names
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
name:
|
||||
description: The name of the series
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the series is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
tags:
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |
|
||||
A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`.
|
||||
type: object
|
||||
values:
|
||||
description: |
|
||||
An array of rows, where each row is an array of values.
|
||||
items:
|
||||
items: {}
|
||||
type: array
|
||||
type: array
|
||||
type: object
|
||||
type: array
|
||||
statement_id:
|
||||
description: |
|
||||
An integer that represents the statement's position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results.
|
||||
type: integer
|
||||
type: object
|
||||
oneOf:
|
||||
- required:
|
||||
- statement_id
|
||||
- error
|
||||
- required:
|
||||
- statement_id
|
||||
- series
|
||||
type: array
|
||||
type: object
|
||||
InfluxQLCSVResponse:
|
||||
type: string
|
||||
example: |
|
||||
name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value
|
||||
Error:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- unprocessable entity
|
||||
- empty value
|
||||
- unavailable
|
||||
- forbidden
|
||||
- too many requests
|
||||
- unauthorized
|
||||
- method not allowed
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
LineProtocolError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- empty value
|
||||
- unavailable
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
op:
|
||||
readOnly: true
|
||||
description: Op describes the logical code operation during error. Useful for debugging.
|
||||
type: string
|
||||
err:
|
||||
readOnly: true
|
||||
description: Err is a stack of errors that occurred during processing of the request. Useful for debugging.
|
||||
type: string
|
||||
line:
|
||||
readOnly: true
|
||||
description: First line within sent body containing malformed data
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- op
|
||||
- err
|
||||
LineProtocolLengthError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- invalid
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
maxLength:
|
||||
readOnly: true
|
||||
description: Max length in bytes for a body of line-protocol.
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- maxLength
|
||||
securitySchemes:
|
||||
TokenAuthentication:
|
||||
type: apiKey
|
||||
name: Authorization
|
||||
in: header
|
||||
description: |
|
||||
Use the [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
scheme to authenticate to the InfluxDB API.
|
||||
|
||||
|
||||
In your API requests, send an `Authorization` header.
|
||||
For the header value, provide the word `Token` followed by a space and an InfluxDB API token.
|
||||
The word `Token` is case-sensitive.
|
||||
|
||||
|
||||
### Syntax
|
||||
|
||||
`Authorization: Token YOUR_INFLUX_TOKEN`
|
||||
|
||||
|
||||
For examples and more information, see the following:
|
||||
- [`/authorizations`](#tag/Authorizations) endpoint.
|
||||
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
|
||||
- [Manage API tokens](/influxdb/cloud/security/tokens/).
|
||||
BasicAuthentication:
|
||||
type: http
|
||||
scheme: basic
|
||||
description: |
|
||||
Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
QuerystringAuthentication:
|
||||
type: apiKey
|
||||
in: query
|
||||
name: u=&p=
|
||||
description: |
|
||||
Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
scheme with InfluxDB 1.x API parameters to provide credentials through the query string.
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
|
|
@ -7,7 +7,7 @@ x-influxdata-product-name: InfluxDB v2 OSS
|
|||
|
||||
apis:
|
||||
v2@2:
|
||||
root: v2/ref.yml
|
||||
root: influxdb-oss-v2-openapi.yaml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb/v2/api/
|
||||
- /influxdb/v2/api/v1-compatibility/
|
||||
|
|
|
|||
|
|
@ -1,15 +0,0 @@
|
|||
title: InfluxDB v1 HTTP API for InfluxDB v2 OSS
|
||||
x-influxdata-short-title: v1 Compatibility API
|
||||
description: |
|
||||
The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB v2 bucket using InfluxDB v1 endpoints.
|
||||
The InfluxDB 1.x compatibility `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
license:
|
||||
name: MIT
|
||||
url: 'https://opensource.org/licenses/MIT'
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
|
|
@ -1,469 +0,0 @@
|
|||
openapi: 3.0.0
|
||||
info:
|
||||
title: InfluxDB v1 HTTP API for InfluxDB v2 OSS
|
||||
version: ''
|
||||
description: |
|
||||
The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB v2 bucket using InfluxDB v1 endpoints.
|
||||
The InfluxDB 1.x compatibility `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
servers:
|
||||
- url: /
|
||||
security:
|
||||
- TokenAuthentication: []
|
||||
- BasicAuthentication: []
|
||||
- QuerystringAuthentication: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: |
|
||||
The InfluxDB 1.x API requires authentication for all requests.
|
||||
InfluxDB Cloud uses InfluxDB API tokens to authenticate requests.
|
||||
|
||||
|
||||
For more information, see the following:
|
||||
- [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
x-traitTag: true
|
||||
- name: Query
|
||||
- name: Write
|
||||
paths:
|
||||
/write:
|
||||
post:
|
||||
operationId: PostWriteV1
|
||||
tags:
|
||||
- Write
|
||||
summary: Write time series data into InfluxDB in a V1-compatible format
|
||||
requestBody:
|
||||
description: Line protocol body
|
||||
required: true
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy.
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: precision
|
||||
schema:
|
||||
type: string
|
||||
description: Write precision.
|
||||
- in: header
|
||||
name: Content-Encoding
|
||||
description: When present, its value indicates to the database that compression is applied to the line protocol body.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
responses:
|
||||
'204':
|
||||
description: Write data is correctly formatted and accepted for writing to the bucket.
|
||||
'400':
|
||||
description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolError'
|
||||
'401':
|
||||
description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'403':
|
||||
description: No token was sent and they are required.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'413':
|
||||
description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolLengthError'
|
||||
'429':
|
||||
description: Token is temporarily over quota. The Retry-After header describes when to try the write again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
'503':
|
||||
description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
default:
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/query:
|
||||
post:
|
||||
operationId: PostQueryV1
|
||||
tags:
|
||||
- Query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
requestBody:
|
||||
description: InfluxQL query to execute.
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: header
|
||||
name: Accept
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
||||
default: application/json
|
||||
enum:
|
||||
- application/json
|
||||
- application/csv
|
||||
- text/csv
|
||||
- application/x-msgpack
|
||||
- in: header
|
||||
name: Accept-Encoding
|
||||
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
- in: header
|
||||
name: Content-Type
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- application/vnd.influxql
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: Bucket to query.
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: q
|
||||
description: Defines the influxql query to run.
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Query results
|
||||
headers:
|
||||
Content-Encoding:
|
||||
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
Trace-Id:
|
||||
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies the request's trace ID.
|
||||
content:
|
||||
application/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
text/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLResponse'
|
||||
examples:
|
||||
influxql-chunk_size_2:
|
||||
value: |
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
|
||||
application/x-msgpack:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'429':
|
||||
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
default:
|
||||
description: Error processing query
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
components:
|
||||
parameters:
|
||||
TraceSpan:
|
||||
in: header
|
||||
name: Zap-Trace-Span
|
||||
description: OpenTracing span context
|
||||
example:
|
||||
trace_id: '1'
|
||||
span_id: '1'
|
||||
baggage:
|
||||
key: value
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
AuthUserV1:
|
||||
in: query
|
||||
name: u
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: Username.
|
||||
AuthPassV1:
|
||||
in: query
|
||||
name: p
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: User token.
|
||||
schemas:
|
||||
InfluxQLResponse:
|
||||
description: |
|
||||
The JSON response for an InfluxQL query.
|
||||
|
||||
A response contains the collection of results for a query.
|
||||
`results` is an array of resultset objects.
|
||||
|
||||
If the response is chunked, the `transfer-encoding` response header is set to `chunked` and each resultset object is sent in a separate JSON object.
|
||||
properties:
|
||||
results:
|
||||
description: |
|
||||
A resultset object that contains the `statement_id` and the `series` array.
|
||||
|
||||
Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the resultset is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
series:
|
||||
description: |
|
||||
An array of series objects--the results of the query. A series of rows shares the same group key returned from the execution of a statement.
|
||||
|
||||
If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
columns:
|
||||
description: An array of column names
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
name:
|
||||
description: The name of the series
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the series is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
tags:
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |
|
||||
A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`.
|
||||
type: object
|
||||
values:
|
||||
description: |
|
||||
An array of rows, where each row is an array of values.
|
||||
items:
|
||||
items: {}
|
||||
type: array
|
||||
type: array
|
||||
type: object
|
||||
type: array
|
||||
statement_id:
|
||||
description: |
|
||||
An integer that represents the statement's position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results.
|
||||
type: integer
|
||||
type: object
|
||||
oneOf:
|
||||
- required:
|
||||
- statement_id
|
||||
- error
|
||||
- required:
|
||||
- statement_id
|
||||
- series
|
||||
type: array
|
||||
type: object
|
||||
InfluxQLCSVResponse:
|
||||
type: string
|
||||
example: |
|
||||
name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value
|
||||
Error:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- unprocessable entity
|
||||
- empty value
|
||||
- unavailable
|
||||
- forbidden
|
||||
- too many requests
|
||||
- unauthorized
|
||||
- method not allowed
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
LineProtocolError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- empty value
|
||||
- unavailable
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
op:
|
||||
readOnly: true
|
||||
description: Op describes the logical code operation during error. Useful for debugging.
|
||||
type: string
|
||||
err:
|
||||
readOnly: true
|
||||
description: Err is a stack of errors that occurred during processing of the request. Useful for debugging.
|
||||
type: string
|
||||
line:
|
||||
readOnly: true
|
||||
description: First line within sent body containing malformed data
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- op
|
||||
- err
|
||||
LineProtocolLengthError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- invalid
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
maxLength:
|
||||
readOnly: true
|
||||
description: Max length in bytes for a body of line-protocol.
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- maxLength
|
||||
securitySchemes:
|
||||
TokenAuthentication:
|
||||
type: apiKey
|
||||
name: Authorization
|
||||
in: header
|
||||
description: |
|
||||
Use the [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
scheme to authenticate to the InfluxDB API.
|
||||
|
||||
|
||||
In your API requests, send an `Authorization` header.
|
||||
For the header value, provide the word `Token` followed by a space and an InfluxDB API token.
|
||||
The word `Token` is case-sensitive.
|
||||
|
||||
|
||||
### Syntax
|
||||
|
||||
`Authorization: Token YOUR_INFLUX_TOKEN`
|
||||
|
||||
|
||||
For examples and more information, see the following:
|
||||
- [`/authorizations`](#tag/Authorizations) endpoint.
|
||||
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
|
||||
- [Manage API tokens](/influxdb/cloud/security/tokens/).
|
||||
BasicAuthentication:
|
||||
type: http
|
||||
scheme: basic
|
||||
description: |
|
||||
Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
QuerystringAuthentication:
|
||||
type: apiKey
|
||||
in: query
|
||||
name: u=&p=
|
||||
description: |
|
||||
Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
scheme with InfluxDB 1.x API parameters to provide credentials through the query string.
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
|
|
@ -67,8 +67,6 @@ tags:
|
|||
|
||||
5. Query data using SQL or InfluxQL with a Flight client or the HTTP API.
|
||||
|
||||
For more information, see the
|
||||
[Get started](/influxdb3/cloud-dedicated/get-started/) guide.
|
||||
- name: Tables
|
||||
description: Manage tables in a database
|
||||
paths:
|
||||
|
|
@ -79,13 +77,13 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to get the [databases](/influxdb3/cloud-dedicated/admin/databases/) for
|
||||
description: The ID of the account to get the databases for
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: clusterId
|
||||
in: path
|
||||
description: The ID of the cluster to get the [databases](/influxdb3/cloud-dedicated/admin/databases/) for
|
||||
description: The ID of the cluster to get the databases for
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -100,7 +98,7 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the database belongs to
|
||||
|
|
@ -186,22 +184,21 @@ paths:
|
|||
|
||||
The retention period is specified in nanoseconds. For example, to set a retention period of 1 hour, use `3600000000000`.
|
||||
|
||||
InfluxDB Cloud Dedicated lets you define a [custom partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/) strategy for each database and table.
|
||||
A _partition_ is a logical grouping of data stored in [Apache Parquet](https://parquet.apache.org/).
|
||||
InfluxDB Cloud Dedicated lets you define a custom partitioning strategy for each database and table.
|
||||
A _partition_ is a logical grouping of data stored in Apache Parquet.
|
||||
By default, data is partitioned by day,
|
||||
but, depending on your schema and workload, customizing the partitioning
|
||||
strategy can improve query performance.
|
||||
|
||||
To use custom partitioning, you define a [partition template](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/).
|
||||
To use custom partitioning, you define a partition template.
|
||||
If a table doesn't have a custom partition template, it inherits the database's template.
|
||||
The partition template is set at the time of database creation and cannot be changed later.
|
||||
For more information, see [Custom partitions](/influxdb3/cloud-dedicated/admin/custom-partitions/).
|
||||
tags:
|
||||
- Databases
|
||||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to create the database for
|
||||
description: The ID of the account to create the database for
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -262,7 +259,7 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the database belongs to
|
||||
|
|
@ -371,7 +368,7 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -429,7 +426,7 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the database belongs to
|
||||
|
|
@ -527,7 +524,7 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -583,8 +580,8 @@ paths:
|
|||
|
||||
Typically, tables are created automatically on write using the measurement name
|
||||
specified in line protocol written to InfluxDB.
|
||||
However, to apply a [custom partition template](/influxdb3/cloud-dedicated/admin/custom-partitions/)
|
||||
to a table, you must manually [create the table with custom partitioning](/influxdb3/cloud-dedicated/admin/tables/#create-a-table-with-custom-partitioning) before you write any data to it.
|
||||
However, to apply a custom partition template
|
||||
to a table, you must manually create the table with custom partitioning before you write any data to it.
|
||||
|
||||
Partitioning defaults to `%Y-%m-%d` (daily).
|
||||
When a partition template is applied to a database, it becomes the default template
|
||||
|
|
@ -595,7 +592,7 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to create the database table for
|
||||
description: The ID of the account to create the database table for
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -653,7 +650,7 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database table belongs to
|
||||
description: The ID of the account that the database table belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the database table belongs to
|
||||
|
|
@ -718,7 +715,7 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database table belongs to
|
||||
description: The ID of the account that the database table belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -762,7 +759,7 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database table belongs to
|
||||
description: The ID of the account that the database table belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -809,7 +806,7 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database table belongs to
|
||||
description: The ID of the account that the database table belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the database table belongs to
|
||||
|
|
@ -863,7 +860,7 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database table belongs to
|
||||
description: The ID of the account that the database table belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -895,7 +892,7 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database table belongs to
|
||||
description: The ID of the account that the database table belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the database table belongs to
|
||||
|
|
@ -947,7 +944,7 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -972,7 +969,7 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the database belongs to
|
||||
|
|
@ -1028,7 +1025,7 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -1069,7 +1066,7 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the database belongs to
|
||||
description: The ID of the account that the database belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the database belongs to
|
||||
|
|
@ -1123,13 +1120,13 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to get the [database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/) for
|
||||
description: The ID of the account to get the database tokens for
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: clusterId
|
||||
in: path
|
||||
description: The ID of the cluster to get the [database tokens](/influxdb3/cloud-dedicated/admin/tokens/database/) for
|
||||
description: The ID of the cluster to get the database tokens for
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -1144,10 +1141,10 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the account that the database token belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the cluster that the database token belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
id:
|
||||
description: The ID of the database token
|
||||
|
|
@ -1225,7 +1222,7 @@ paths:
|
|||
tags:
|
||||
- Database tokens
|
||||
description: |
|
||||
Create a [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) for a cluster.
|
||||
Create a database token for a cluster.
|
||||
|
||||
The token returned on the `accessToken` property in the response can be used to authenticate query and write requests to the cluster.
|
||||
|
||||
|
|
@ -1238,19 +1235,19 @@ paths:
|
|||
#### Store secure tokens in a secret store
|
||||
|
||||
We recommend storing database tokens in a **secure secret store**.
|
||||
For example, see how to [authenticate Telegraf using tokens in your OS secret store](https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os).
|
||||
For example, see how to authenticate Telegraf using tokens in your OS secret store.
|
||||
|
||||
If you lose a token, [delete the token from InfluxDB](/influxdb3/cloud-dedicated/admin/tokens/database/delete/) and create a new one.
|
||||
If you lose a token, delete the token from InfluxDB and create a new one.
|
||||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) to create the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) for
|
||||
description: The ID of the account to create the database token for
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: clusterId
|
||||
in: path
|
||||
description: The ID of the cluster to create the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) for
|
||||
description: The ID of the cluster to create the database token for
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -1300,10 +1297,10 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the account that the database token belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the cluster that the database token belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
id:
|
||||
description: The ID of the database token
|
||||
|
|
@ -1412,7 +1409,7 @@ paths:
|
|||
operationId: GetDatabaseToken
|
||||
summary: Get a database token
|
||||
description: |
|
||||
Retrieve metadata details for a [database token](/influxdb3/cloud-dedicated/admin/tokens/database/).
|
||||
Retrieve metadata details for a database token.
|
||||
|
||||
#### Store secure tokens in a secret store
|
||||
|
||||
|
|
@ -1424,19 +1421,19 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the account that the database token belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: clusterId
|
||||
in: path
|
||||
description: The ID of the cluster that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the cluster that the database token belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: tokenId
|
||||
in: path
|
||||
description: The ID of the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) to get
|
||||
description: The ID of the database token to get
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -1449,10 +1446,10 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the account that the database token belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the cluster that the database token belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
id:
|
||||
description: The ID of the database token
|
||||
|
|
@ -1538,25 +1535,25 @@ paths:
|
|||
operationId: UpdateDatabaseToken
|
||||
summary: Update a database token
|
||||
description: |
|
||||
Update the description and permissions of a [database token](/influxdb3/cloud-dedicated/admin/tokens/database/).
|
||||
Update the description and permissions of a database token.
|
||||
tags:
|
||||
- Database tokens
|
||||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the account that the database token belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: clusterId
|
||||
in: path
|
||||
description: The ID of the cluster that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the cluster that the database token belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: tokenId
|
||||
in: path
|
||||
description: The ID of the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) to update
|
||||
description: The ID of the database token to update
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
requestBody:
|
||||
|
|
@ -1610,10 +1607,10 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
accountId:
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the account that the database token belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
clusterId:
|
||||
description: The ID of the cluster that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the cluster that the database token belongs to
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
id:
|
||||
description: The ID of the database token
|
||||
|
|
@ -1743,19 +1740,19 @@ paths:
|
|||
parameters:
|
||||
- name: accountId
|
||||
in: path
|
||||
description: The ID of the [account](/influxdb3/cloud-dedicated/get-started/setup/#request-an-influxdb-cloud-dedicated-cluster) that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the account that the database token belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: clusterId
|
||||
in: path
|
||||
description: The ID of the cluster that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) belongs to
|
||||
description: The ID of the cluster that the database token belongs to
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
- name: tokenId
|
||||
in: path
|
||||
description: The ID of the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) to delete
|
||||
description: The ID of the database token to delete
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -1841,7 +1838,7 @@ components:
|
|||
minimum: 1
|
||||
ClusterDatabaseRetentionPeriod:
|
||||
description: |
|
||||
The retention period of the [cluster database](/influxdb3/cloud-dedicated/admin/databases/) in nanoseconds, if applicable
|
||||
The retention period of the cluster database in nanoseconds, if applicable
|
||||
|
||||
If the retention period is not set or is set to 0, the database will have infinite retention
|
||||
type: integer
|
||||
|
|
@ -1871,7 +1868,7 @@ components:
|
|||
minimum: 1
|
||||
ClusterDatabasePartitionTemplate:
|
||||
description: |
|
||||
A template for [partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/) a cluster database.
|
||||
A template for partitioning a cluster database.
|
||||
|
||||
Each partition template part is evaluated in sequence.
|
||||
The outputs from each part are concatenated with the
|
||||
|
|
@ -1915,7 +1912,7 @@ components:
|
|||
* `time=2023-01-01, a=<long string>` -> `2023|<long string>#|!|!`
|
||||
* `time=2023-01-01, c=<long string>` -> `2023|!|!|<bucket ID for untruncated long string>`
|
||||
|
||||
When using the default [partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/) template (YYYY-MM-DD) there is no
|
||||
When using the default partitioning template (YYYY-MM-DD) there is no
|
||||
encoding necessary, as the derived partition key contains a single part, and
|
||||
no reserved characters. [`TemplatePart::Bucket`] parts by definition will
|
||||
always be within the part length limit and contain no restricted characters
|
||||
|
|
@ -2017,7 +2014,7 @@ components:
|
|||
tagName: c
|
||||
numberOfBuckets: 10
|
||||
ClusterDatabaseTableName:
|
||||
description: The name of the [cluster database](/influxdb3/cloud-dedicated/admin/databases/) table
|
||||
description: The name of the cluster database table
|
||||
type: string
|
||||
examples:
|
||||
- TableOne
|
||||
|
|
@ -2030,15 +2027,15 @@ components:
|
|||
- Limited Access Token
|
||||
- Full Access Token
|
||||
DatabaseTokenResourceAllDatabases:
|
||||
description: A resource value for a [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) permission that refers to all databases
|
||||
description: A resource value for a database token permission that refers to all databases
|
||||
type: string
|
||||
enum:
|
||||
- '*'
|
||||
DatabaseTokenPermissionAction:
|
||||
description: The action the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) permission allows
|
||||
description: The action the database token permission allows
|
||||
type: string
|
||||
DatabaseTokenPermissionResource:
|
||||
description: The resource the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) permission applies to
|
||||
description: The resource the database token permission applies to
|
||||
anyOf:
|
||||
- $ref: '#/components/schemas/ClusterDatabaseName'
|
||||
- $ref: '#/components/schemas/DatabaseTokenResourceAllDatabases'
|
||||
|
|
@ -2062,7 +2059,7 @@ components:
|
|||
- action: write
|
||||
resource: '*'
|
||||
DatabaseTokenPermissions:
|
||||
description: The list of permissions the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) allows
|
||||
description: The list of permissions the database token allows
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/DatabaseTokenPermission'
|
||||
|
|
@ -2075,7 +2072,7 @@ components:
|
|||
resource: '*'
|
||||
DatabaseTokenCreatedAt:
|
||||
description: |
|
||||
The date and time that the [database token](/influxdb3/cloud-dedicated/admin/tokens/database/) was created
|
||||
The date and time that the database token was created
|
||||
|
||||
Uses RFC3339 format
|
||||
$ref: '#/components/schemas/DateTimeRfc3339'
|
||||
|
|
|
|||
|
|
@ -5,7 +5,11 @@ tags:
|
|||
InfluxDB 3 Cloud Dedicated databases.
|
||||
x-related:
|
||||
- title: Manage database tokens
|
||||
href: /influxdb3/cloud-dedicated/admin/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
|
||||
|
||||
Databases:
|
||||
description: >
|
||||
|
|
@ -14,11 +18,20 @@ tags:
|
|||
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/
|
||||
|
||||
Quick start:
|
||||
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/
|
||||
# x-traitTag: true — informational tag, no operations
|
||||
|
||||
Tables:
|
||||
|
|
@ -28,3 +41,7 @@ tags:
|
|||
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/
|
||||
|
|
|
|||
|
|
@ -1,21 +0,0 @@
|
|||
title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Dedicated
|
||||
x-influxdata-short-title: v1 Compatibility API
|
||||
x-influxdata-short-description: The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB 3 Cloud Dedicated database using InfluxDB v1 endpoints.
|
||||
description: |
|
||||
The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB 3 Cloud Dedicated database using InfluxDB v1 endpoints.
|
||||
|
||||
The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
|
||||
#### Related
|
||||
|
||||
[InfluxDB `/api/v2` API for InfluxDB 3 Cloud Dedicated](/influxdb3/cloud-dedicated/api/v2/)
|
||||
license:
|
||||
name: MIT
|
||||
url: 'https://opensource.org/licenses/MIT'
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
|
|
@ -1,773 +0,0 @@
|
|||
openapi: 3.0.0
|
||||
info:
|
||||
title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Dedicated
|
||||
version: ''
|
||||
description: |
|
||||
The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB 3 Cloud Dedicated database using InfluxDB v1 endpoints.
|
||||
|
||||
The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
|
||||
#### Related
|
||||
|
||||
[InfluxDB `/api/v2` API for InfluxDB 3 Cloud Dedicated](/influxdb3/cloud-dedicated/api/v2/)
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
servers:
|
||||
- url: /
|
||||
security:
|
||||
- TokenAuthentication: []
|
||||
- BasicAuthentication: []
|
||||
- QuerystringAuthentication: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: |
|
||||
The InfluxDB 1.x API requires authentication for all requests.
|
||||
InfluxDB Cloud uses InfluxDB API tokens to authenticate requests.
|
||||
|
||||
|
||||
For more information, see the following:
|
||||
- [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
x-traitTag: true
|
||||
- name: Ping
|
||||
- name: Query
|
||||
- name: Write
|
||||
paths:
|
||||
/write:
|
||||
post:
|
||||
operationId: PostWriteV1
|
||||
tags:
|
||||
- Write
|
||||
summary: Write time series data into InfluxDB in a V1-compatible format
|
||||
requestBody:
|
||||
description: Line protocol body
|
||||
required: true
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: |
|
||||
The database to write to.
|
||||
|
||||
**Database targeting:** In Cloud Dedicated, databases can be named using the `database_name/retention_policy_name` convention for InfluxQL compatibility. Cloud Dedicated does not use DBRP mappings. The db and rp parameters are used to construct the target database name following this naming convention.
|
||||
|
||||
**Auto-creation behavior:** Cloud Dedicated requires databases to be created before writing data. The v1 `/write` API does not automatically create databases. If the specified
|
||||
database does not exist, the write request will fail.
|
||||
|
||||
Authentication: Requires a valid API token with _write_ permissions for the target database.
|
||||
|
||||
### Related
|
||||
|
||||
- [Write data to InfluxDB Cloud Dedicated](/influxdb3/cloud-dedicated/write-data/)
|
||||
- [Manage databases in InfluxDB Cloud Dedicated](/influxdb3/cloud-dedicated/admin/databases/)
|
||||
- [InfluxQL DBRP naming convention](/influxdb3/cloud-dedicated/admin/databases/create/#influxql-dbrp-naming-convention)
|
||||
- [InfluxQL data retention policy mapping differences](/influxdb3/cloud-serverless/guides/prototype-evaluation/#influxql-data-retention-policy-mapping-differences)
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: precision
|
||||
schema:
|
||||
type: string
|
||||
description: Write precision.
|
||||
- in: header
|
||||
name: Content-Encoding
|
||||
description: When present, its value indicates to the database that compression is applied to the line protocol body.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
responses:
|
||||
'204':
|
||||
description: Write data is correctly formatted and accepted for writing to the bucket.
|
||||
'400':
|
||||
description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolError'
|
||||
'401':
|
||||
description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'403':
|
||||
description: No token was sent and they are required.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'413':
|
||||
description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolLengthError'
|
||||
'429':
|
||||
description: Token is temporarily over quota or ingesters are resource constrained.
|
||||
'503':
|
||||
description: Server is temporarily unavailable to accept writes due to too many concurrent requests or insufficient healthy ingesters.
|
||||
default:
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/query:
|
||||
get:
|
||||
operationId: GetQueryV1
|
||||
tags:
|
||||
- Query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: header
|
||||
name: Accept
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
||||
default: application/json
|
||||
enum:
|
||||
- application/json
|
||||
- application/csv
|
||||
- text/csv
|
||||
- application/x-msgpack
|
||||
- in: header
|
||||
name: Accept-Encoding
|
||||
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
- in: query
|
||||
name: chunked
|
||||
description: |
|
||||
If true, the response is divided into chunks of size `chunk_size`.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
- in: query
|
||||
name: chunk_size
|
||||
description: |
|
||||
The number of records that will go into a chunk.
|
||||
This parameter is only used if `chunked=true`.
|
||||
schema:
|
||||
type: integer
|
||||
default: 10000
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: The database to query from.
|
||||
- in: query
|
||||
name: pretty
|
||||
description: |
|
||||
If true, the JSON response is formatted in a human-readable format.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
- in: query
|
||||
name: q
|
||||
description: Defines the InfluxQL query to run.
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: |
|
||||
The retention policy name for InfluxQL compatibility
|
||||
|
||||
Optional parameter that, when combined with the db parameter, forms the complete database name to query. In InfluxDB Cloud Dedicated, databases can be named using the
|
||||
database_name/retention_policy_name convention for InfluxQL compatibility.
|
||||
|
||||
When a request specifies both `db` and `rp`, Cloud Dedicated combines them as `db/rp` to target the database--for example:
|
||||
|
||||
- If `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`
|
||||
- If only `db=mydb` is provided (no `rp`), the query targets the database named `mydb`
|
||||
|
||||
Unlike InfluxDB v1 and Cloud Serverless, Cloud Dedicated does not use DBRP mappings or separate retention policy objects. This parameter exists solely for v1 API
|
||||
compatibility and database naming conventions.
|
||||
|
||||
_Note: The retention policy name does not control data retention in Cloud Dedicated. Data retention is determined by the database's **retention period** setting._
|
||||
|
||||
### Related
|
||||
|
||||
- [InfluxQL DBRP naming convention](/influxdb3/cloud-dedicated/admin/databases/create/#influxql-dbrp-naming-convention)
|
||||
- [InfluxQL data retention policy mapping differences](/influxdb3/cloud-serverless/guides/prototype-evaluation/#influxql-data-retention-policy-mapping-differences)
|
||||
- name: epoch
|
||||
description: |
|
||||
Formats timestamps as unix (epoch) timestamps with the specified precision
|
||||
instead of RFC3339 timestamps with nanosecond precision.
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- h
|
||||
- m
|
||||
- s
|
||||
- ms
|
||||
- u
|
||||
- µ
|
||||
- ns
|
||||
responses:
|
||||
'200':
|
||||
description: Query results
|
||||
headers:
|
||||
Content-Encoding:
|
||||
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
Trace-Id:
|
||||
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies the request's trace ID.
|
||||
content:
|
||||
application/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
text/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLResponse'
|
||||
examples:
|
||||
influxql-chunk_size_2:
|
||||
value: |
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
|
||||
application/x-msgpack:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'429':
|
||||
description: Token is temporarily over quota or the querier is resource constrained.
|
||||
default:
|
||||
description: Error processing query
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
post:
|
||||
operationId: PostQueryV1
|
||||
tags:
|
||||
- Query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
requestBody:
|
||||
description: InfluxQL query to execute.
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
db:
|
||||
type: string
|
||||
description: |
|
||||
The database name for InfluxQL queries.
|
||||
|
||||
Required parameter that specifies the database to query.
|
||||
In InfluxDB Cloud Dedicated, this can be either:
|
||||
- A simple database name (for example, `mydb`)
|
||||
- The database portion of a `database_name/retention_policy_name` naming convention (used together with the `rp` parameter)
|
||||
|
||||
When used alone, `db` specifies the complete database name to query. When used with the `rp` parameter, they combine to form the full database name as `db/rp`--for example, if `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`.
|
||||
|
||||
Unlike InfluxDB Cloud Serverless, Cloud Dedicated does not use DBRP mappings. The database name directly corresponds to an existing database in your Cloud Dedicated cluster.
|
||||
|
||||
Examples:
|
||||
- `db=mydb` - queries the database named `mydb`
|
||||
- `db=mydb` with `rp=autogen` - queries the database named `mydb/autogen`
|
||||
|
||||
_Note: The specified database must exist in your Cloud Dedicated cluster. Queries will fail if the database does not exist._
|
||||
|
||||
### Related
|
||||
|
||||
- [InfluxQL DBRP naming convention](/influxdb3/cloud-dedicated/admin/databases/create/#influxql-dbrp-naming-convention)
|
||||
- [Migrate data from InfluxDB 1.x to Cloud Dedicated](/influxdb3/cloud-dedicated/guides/migrate-data/migrate-1x-to-cloud-dedicated/)
|
||||
- [InfluxQL data retention policy mapping differences between InfluxDB Cloud Dedicated and Cloud Serverless](/influxdb3/cloud-serverless/guides/prototype-evaluation/#influxql-data-retention-policy-mapping-differences)
|
||||
rp:
|
||||
description: |
|
||||
The retention policy name for InfluxQL compatibility
|
||||
|
||||
Optional parameter that, when combined with the db parameter, forms the complete database name to query. In InfluxDB Cloud Dedicated, databases can be named using the
|
||||
database_name/retention_policy_name convention for InfluxQL compatibility.
|
||||
|
||||
When a request specifies both `db` and `rp`, Cloud Dedicated combines them as `db/rp` to target the database--for example:
|
||||
|
||||
- If `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`
|
||||
- If only `db=mydb` is provided (no `rp`), the query targets the database named `mydb`
|
||||
|
||||
Unlike InfluxDB v1 and Cloud Serverless, Cloud Dedicated does not use DBRP mappings or separate retention policy objects. This parameter exists solely for v1 API
|
||||
compatibility and database naming conventions.
|
||||
|
||||
_Note: The retention policy name does not control data retention in Cloud Dedicated. Data retention is determined by the database's **retention period** setting._
|
||||
|
||||
### Related
|
||||
|
||||
- [InfluxQL DBRP naming convention](/influxdb3/cloud-dedicated/admin/databases/create/#influxql-dbrp-naming-convention)
|
||||
- [Migrate data from InfluxDB 1.x to Cloud Dedicated](/influxdb3/cloud-dedicated/guides/migrate-data/migrate-1x-to-cloud-dedicated/)
|
||||
- [InfluxQL data retention policy mapping differences](/influxdb3/cloud-serverless/guides/prototype-evaluation/#influxql-data-retention-policy-mapping-differences)
|
||||
type: string
|
||||
q:
|
||||
description: Defines the InfluxQL query to run.
|
||||
type: string
|
||||
chunked:
|
||||
description: |
|
||||
If true, the response is divided into chunks of size `chunk_size`.
|
||||
type: boolean
|
||||
chunk_size:
|
||||
description: |
|
||||
The number of records that will go into a chunk.
|
||||
This parameter is only used if `chunked=true`.
|
||||
type: integer
|
||||
default: 10000
|
||||
epoch:
|
||||
description: |
|
||||
A unix timestamp precision.
|
||||
type: string
|
||||
enum:
|
||||
- h
|
||||
- m
|
||||
- s
|
||||
- ms
|
||||
- u
|
||||
- µ
|
||||
- ns
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: header
|
||||
name: Accept
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
||||
default: application/json
|
||||
enum:
|
||||
- application/json
|
||||
- application/csv
|
||||
- text/csv
|
||||
- application/x-msgpack
|
||||
- in: header
|
||||
name: Accept-Encoding
|
||||
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
- in: header
|
||||
name: Content-Type
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- application/vnd.influxql
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: Database to query.
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: q
|
||||
description: Defines the influxql query to run.
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Query results
|
||||
headers:
|
||||
Content-Encoding:
|
||||
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
Trace-Id:
|
||||
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies the request's trace ID.
|
||||
content:
|
||||
application/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
text/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLResponse'
|
||||
examples:
|
||||
influxql-chunk_size_2:
|
||||
value: |
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
|
||||
application/x-msgpack:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'429':
|
||||
description: Token is temporarily over quota or queriers are resource constrained.
|
||||
default:
|
||||
description: Error processing query
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/ping:
|
||||
get:
|
||||
description: |
|
||||
Reports the InfluxQL bridge querier health and the InfluxDB version of the instance.
|
||||
|
||||
The response is a HTTP `204` status code to inform you the querier is available.
|
||||
|
||||
For InfluxDB 3 Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters.
|
||||
|
||||
To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb3/cloud-dedicated/api/v2/#tag/Write).
|
||||
|
||||
This endpoint doesn't require authentication.
|
||||
operationId: GetPing
|
||||
responses:
|
||||
'204':
|
||||
description: |
|
||||
Success--the querier is available.
|
||||
Headers contain InfluxDB version information.
|
||||
headers:
|
||||
X-Influxdb-Build:
|
||||
description: |
|
||||
The type of InfluxDB build.
|
||||
schema:
|
||||
type: string
|
||||
X-Influxdb-Version:
|
||||
description: |
|
||||
The version of InfluxDB.
|
||||
schema:
|
||||
type: integer
|
||||
4xx:
|
||||
description: |
|
||||
#### InfluxDB Cloud
|
||||
- Doesn't return this error.
|
||||
security:
|
||||
- {}
|
||||
servers: []
|
||||
summary: Get the status of the instance
|
||||
tags:
|
||||
- Ping
|
||||
head:
|
||||
description: |
|
||||
Reports the InfluxQL bridge querier health and the InfluxDB version of the instance.
|
||||
|
||||
The response is a HTTP `204` status code to inform you the querier is available.
|
||||
|
||||
For InfluxDB 3 Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters.
|
||||
|
||||
To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb3/cloud-dedicated/api/v2/#tag/Write).
|
||||
|
||||
This endpoint doesn't require authentication.
|
||||
operationId: HeadPing
|
||||
responses:
|
||||
'204':
|
||||
description: |
|
||||
Success--the querier is available.
|
||||
Headers contain InfluxDB version information.
|
||||
headers:
|
||||
X-Influxdb-Build:
|
||||
description: The type of InfluxDB build.
|
||||
schema:
|
||||
type: string
|
||||
X-Influxdb-Version:
|
||||
description: |
|
||||
The version of InfluxDB.
|
||||
schema:
|
||||
type: integer
|
||||
4xx:
|
||||
description: |
|
||||
#### InfluxDB Cloud
|
||||
- Doesn't return this error.
|
||||
security:
|
||||
- {}
|
||||
servers: []
|
||||
summary: Get the status of the instance
|
||||
tags:
|
||||
- Ping
|
||||
components:
|
||||
parameters:
|
||||
TraceSpan:
|
||||
in: header
|
||||
name: Zap-Trace-Span
|
||||
description: OpenTracing span context
|
||||
example:
|
||||
trace_id: '1'
|
||||
span_id: '1'
|
||||
baggage:
|
||||
key: value
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
AuthUserV1:
|
||||
in: query
|
||||
name: u
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: Username.
|
||||
AuthPassV1:
|
||||
in: query
|
||||
name: p
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: User token.
|
||||
schemas:
|
||||
InfluxQLResponse:
|
||||
description: |
|
||||
The JSON response for an InfluxQL query.
|
||||
|
||||
A response contains the collection of results for a query.
|
||||
`results` is an array of resultset objects.
|
||||
|
||||
If the response is chunked, the `transfer-encoding` response header is set to `chunked` and each resultset object is sent in a separate JSON object.
|
||||
properties:
|
||||
results:
|
||||
description: |
|
||||
A resultset object that contains the `statement_id` and the `series` array.
|
||||
|
||||
Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the resultset is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
series:
|
||||
description: |
|
||||
An array of series objects--the results of the query. A series of rows shares the same group key returned from the execution of a statement.
|
||||
|
||||
If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
columns:
|
||||
description: An array of column names
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
name:
|
||||
description: The name of the series
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the series is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
tags:
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |
|
||||
A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`.
|
||||
type: object
|
||||
values:
|
||||
description: |
|
||||
An array of rows, where each row is an array of values.
|
||||
items:
|
||||
items: {}
|
||||
type: array
|
||||
type: array
|
||||
type: object
|
||||
type: array
|
||||
statement_id:
|
||||
description: |
|
||||
An integer that represents the statement's position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results.
|
||||
type: integer
|
||||
type: object
|
||||
oneOf:
|
||||
- required:
|
||||
- statement_id
|
||||
- error
|
||||
- required:
|
||||
- statement_id
|
||||
- series
|
||||
type: array
|
||||
type: object
|
||||
InfluxQLCSVResponse:
|
||||
type: string
|
||||
example: |
|
||||
name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value
|
||||
Error:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- unprocessable entity
|
||||
- empty value
|
||||
- unavailable
|
||||
- forbidden
|
||||
- too many requests
|
||||
- unauthorized
|
||||
- method not allowed
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
LineProtocolError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- empty value
|
||||
- unavailable
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
op:
|
||||
readOnly: true
|
||||
description: Op describes the logical code operation during error. Useful for debugging.
|
||||
type: string
|
||||
err:
|
||||
readOnly: true
|
||||
description: Err is a stack of errors that occurred during processing of the request. Useful for debugging.
|
||||
type: string
|
||||
line:
|
||||
readOnly: true
|
||||
description: First line within sent body containing malformed data
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- op
|
||||
- err
|
||||
LineProtocolLengthError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- invalid
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
maxLength:
|
||||
readOnly: true
|
||||
description: Max length in bytes for a body of line-protocol.
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- maxLength
|
||||
securitySchemes:
|
||||
TokenAuthentication:
|
||||
type: apiKey
|
||||
name: Authorization
|
||||
in: header
|
||||
description: |
|
||||
Use the [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
scheme to authenticate to the InfluxDB API.
|
||||
|
||||
|
||||
In your API requests, send an `Authorization` header.
|
||||
For the header value, provide the word `Token` followed by a space and an InfluxDB API token.
|
||||
The word `Token` is case-sensitive.
|
||||
|
||||
|
||||
### Syntax
|
||||
|
||||
`Authorization: Token YOUR_INFLUX_TOKEN`
|
||||
|
||||
|
||||
For examples and more information, see the following:
|
||||
- [`/authorizations`](#tag/Authorizations) endpoint.
|
||||
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
|
||||
- [Manage API tokens](/influxdb/cloud/security/tokens/).
|
||||
BasicAuthentication:
|
||||
type: http
|
||||
scheme: basic
|
||||
description: |
|
||||
Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
QuerystringAuthentication:
|
||||
type: apiKey
|
||||
in: query
|
||||
name: u=&p=
|
||||
description: |
|
||||
Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
scheme with InfluxDB 1.x API parameters to provide credentials through the query string.
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
|
|
@ -10,7 +10,5 @@ apis:
|
|||
root: influxdb3-cloud-serverless-openapi.yaml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb3/cloud-serverless/api/
|
||||
v1-compatibility@2:
|
||||
root: v1-compatibility/swaggerV1Compat.yml
|
||||
x-influxdata-docs-aliases:
|
||||
- /influxdb3/cloud-serverless/api/v1/
|
||||
- /influxdb3/cloud-serverless/api/v1-compatibility/
|
||||
|
|
|
|||
|
|
@ -1,21 +0,0 @@
|
|||
title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Serverless
|
||||
x-influxdata-short-title: v1 Compatibility API
|
||||
x-influxdata-short-description: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket.
|
||||
description: |
|
||||
The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket.
|
||||
|
||||
The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
|
||||
#### Related
|
||||
|
||||
[InfluxDB `/api/v2` API for InfluxDB 3 Cloud Serverless](/influxdb3/cloud-serverless/api/v2/)
|
||||
license:
|
||||
name: MIT
|
||||
url: 'https://opensource.org/licenses/MIT'
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
|
|
@ -1,737 +0,0 @@
|
|||
openapi: 3.0.0
|
||||
info:
|
||||
title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Serverless
|
||||
version: ''
|
||||
description: |
|
||||
The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket.
|
||||
|
||||
The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
|
||||
#### Related
|
||||
|
||||
[InfluxDB `/api/v2` API for InfluxDB 3 Cloud Serverless](/influxdb3/cloud-serverless/api/v2/)
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
servers:
|
||||
- url: /
|
||||
security:
|
||||
- TokenAuthentication: []
|
||||
- BasicAuthentication: []
|
||||
- QuerystringAuthentication: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: |
|
||||
The InfluxDB 1.x API requires authentication for all requests.
|
||||
InfluxDB Cloud uses InfluxDB API tokens to authenticate requests.
|
||||
|
||||
|
||||
For more information, see the following:
|
||||
- [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
x-traitTag: true
|
||||
- name: Query
|
||||
- name: Write
|
||||
paths:
|
||||
/write:
|
||||
post:
|
||||
operationId: PostWriteV1
|
||||
tags:
|
||||
- Write
|
||||
summary: Write time series data into InfluxDB in a V1-compatible format
|
||||
requestBody:
|
||||
description: Line protocol body
|
||||
required: true
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: Database to write to. If none exists, InfluxDB creates a database with a default 3-day retention policy.
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: precision
|
||||
schema:
|
||||
type: string
|
||||
description: Write precision.
|
||||
- in: header
|
||||
name: Content-Encoding
|
||||
description: When present, its value indicates to the database that compression is applied to the line protocol body.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
responses:
|
||||
'204':
|
||||
description: Write data is correctly formatted and accepted for writing to the bucket.
|
||||
'400':
|
||||
description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolError'
|
||||
'401':
|
||||
description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'403':
|
||||
description: No token was sent and they are required.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'413':
|
||||
description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolLengthError'
|
||||
'429':
|
||||
description: Token is temporarily over quota. The Retry-After header describes when to try the write again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
'503':
|
||||
description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
default:
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/query:
|
||||
get:
|
||||
operationId: GetQueryV1
|
||||
tags:
|
||||
- Query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: header
|
||||
name: Accept
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
||||
default: application/json
|
||||
enum:
|
||||
- application/json
|
||||
- application/csv
|
||||
- text/csv
|
||||
- application/x-msgpack
|
||||
- in: header
|
||||
name: Accept-Encoding
|
||||
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
- in: query
|
||||
name: chunked
|
||||
description: |
|
||||
If true, the response is divided into chunks of size `chunk_size`.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
- in: query
|
||||
name: chunk_size
|
||||
description: |
|
||||
The number of records that will go into a chunk.
|
||||
This parameter is only used if `chunked=true`.
|
||||
schema:
|
||||
type: integer
|
||||
default: 10000
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: |
|
||||
The database name for InfluxQL queries
|
||||
|
||||
Required parameter that specifies the database to query via DBRP (Database Retention Policy) mapping. In Cloud Serverless, this parameter is used together with DBRP
|
||||
mappings to identify which bucket to query.
|
||||
|
||||
The `db` parameter (optionally combined with `rp`) must have an existing DBRP mapping that points to a bucket. Without a valid DBRP mapping, queries will fail with an
|
||||
authorization error.
|
||||
|
||||
**DBRP mapping requirements:**
|
||||
- A DBRP mapping must exist before querying
|
||||
- Mappings can be created automatically when writing data with the v1 API (if your token has permissions)
|
||||
- Mappings can be created manually using the InfluxDB CLI or API
|
||||
|
||||
### Examples
|
||||
- `db=mydb` - uses the default DBRP mapping for `mydb`
|
||||
- `db=mydb` with `rp=weekly` - uses the DBRP mapping for `mydb/weekly`
|
||||
|
||||
_Note: Unlike the v1 `/write` endpoint which can auto-create buckets and mappings, the `/query` endpoint requires pre-existing DBRP mappings. The actual data is stored in and
|
||||
queried from the bucket that the DBRP mapping points to._
|
||||
|
||||
### Related
|
||||
|
||||
- [Use the InfluxDB v1 query API and InfluxQL in Cloud Serverless](/influxdb3/cloud-serverless/query-data/execute-queries/v1-http/)
|
||||
- [Map v1 databases and retention policies to buckets in Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
|
||||
- [Migrate from InfluxDB 1.x to Cloud Serverless](/influxdb3/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless/)
|
||||
- in: query
|
||||
name: pretty
|
||||
description: |
|
||||
If true, the JSON response is formatted in a human-readable format.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
- in: query
|
||||
name: q
|
||||
description: Defines the InfluxQL query to run.
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: |
|
||||
The retention policy name for InfluxQL queries
|
||||
|
||||
Optional parameter that specifies the retention policy to use when querying data with InfluxQL. In Cloud Serverless, this parameter works with DBRP (Database Retention
|
||||
Policy) mappings to identify the target bucket.
|
||||
|
||||
When provided together with the `db` parameter, Cloud Serverless uses the DBRP mapping to determine which bucket to query. The combination of `db` and `rp` must have an
|
||||
existing DBRP mapping that points to a bucket. If no `rp` is specified, Cloud Serverless uses the default retention policy mapping for the database.
|
||||
|
||||
Requirements: A DBRP mapping must exist for the db/rp combination before you can query data. DBRP mappings can be created:
|
||||
- Automatically when writing data with the v1 API (if your token has sufficient permissions)
|
||||
- Manually using the InfluxDB CLI or API
|
||||
|
||||
Example: If `db=mydb` and `rp=weekly`, the query uses the DBRP mapping for `mydb/weekly` to determine which bucket to query.
|
||||
|
||||
_Note: The retention policy name is used only for DBRP mapping. Actual data retention is controlled by the target bucket's retention period setting, not by the retention
|
||||
policy name._
|
||||
|
||||
### Related
|
||||
|
||||
- [Use the InfluxDB v1 query API and InfluxQL in Cloud Serverless](/influxdb3/cloud-serverless/query-data/execute-queries/v1-http/)
|
||||
- [Map v1 databases and retention policies to buckets in Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
|
||||
- [Migrate from InfluxDB 1.x to Cloud Serverless](/influxdb3/cloud-serverless/guides/migrate-data/migrate-1x-to-serverless/)
|
||||
- name: epoch
|
||||
description: |
|
||||
Formats timestamps as unix (epoch) timestamps with the specified precision
|
||||
instead of RFC3339 timestamps with nanosecond precision.
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- h
|
||||
- m
|
||||
- s
|
||||
- ms
|
||||
- u
|
||||
- µ
|
||||
- ns
|
||||
responses:
|
||||
'200':
|
||||
description: Query results
|
||||
headers:
|
||||
Content-Encoding:
|
||||
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
Trace-Id:
|
||||
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies the request's trace ID.
|
||||
content:
|
||||
application/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
text/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLResponse'
|
||||
examples:
|
||||
influxql-chunk_size_2:
|
||||
value: |
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
|
||||
application/x-msgpack:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'429':
|
||||
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
default:
|
||||
description: Error processing query
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
post:
|
||||
operationId: PostQueryV1
|
||||
tags:
|
||||
- Query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
requestBody:
|
||||
description: InfluxQL query to execute.
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
db:
|
||||
type: string
|
||||
description: |
|
||||
The database name for InfluxQL queries
|
||||
|
||||
Required parameter that specifies the database to query via DBRP (Database Retention Policy) mapping. In Cloud Serverless, this parameter is used together with DBRP
|
||||
mappings to identify which bucket to query.
|
||||
|
||||
The `db` parameter (optionally combined with `rp`) must have an existing DBRP mapping that points to a bucket. Without a valid DBRP mapping, queries will fail with an
|
||||
authorization error.
|
||||
|
||||
**DBRP mapping requirements:**
|
||||
- A DBRP mapping must exist before querying
|
||||
- Mappings can be created automatically when writing data with the v1 API (if your token has permissions)
|
||||
- Mappings can be created manually using the InfluxDB CLI or API
|
||||
|
||||
### Examples
|
||||
- `db=mydb` - uses the default DBRP mapping for `mydb`
|
||||
- `db=mydb` with `rp=weekly` - uses the DBRP mapping for `mydb/weekly`
|
||||
|
||||
_Note: Unlike the v1 `/write` endpoint which can auto-create buckets and mappings, the `/query` endpoint requires pre-existing DBRP mappings. The actual data is stored in and
|
||||
queried from the bucket that the DBRP mapping points to._
|
||||
|
||||
### Related
|
||||
|
||||
- [Execute InfluxQL queries using the v1 API](/influxdb3/cloud-serverless/query-data/execute-queries/influxql/api/v1-http/)
|
||||
- [Map v1 databases and retention policies to buckets in Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
|
||||
- [Manage DBRP mappings in Cloud Serverless](/influxdb3/cloud-serverless/admin/dbrp/)
|
||||
rp:
|
||||
description: |
|
||||
The retention policy name for InfluxQL queries
|
||||
|
||||
Optional parameter that specifies the retention policy to use when querying data with InfluxQL. In Cloud Serverless, this parameter works with DBRP (Database Retention
|
||||
Policy) mappings to identify the target bucket.
|
||||
|
||||
When provided together with the `db` parameter, Cloud Serverless uses the DBRP mapping to determine which bucket to query. The combination of `db` and `rp` must have an
|
||||
existing DBRP mapping that points to a bucket. If no `rp` is specified, Cloud Serverless uses the default retention policy mapping for the database.
|
||||
|
||||
Requirements: A DBRP mapping must exist for the db/rp combination before you can query data. DBRP mappings can be created:
|
||||
- Automatically when writing data with the v1 API (if your token has sufficient permissions)
|
||||
- Manually using the InfluxDB CLI or API
|
||||
|
||||
Example: If `db=mydb` and `rp=weekly`, the query uses the DBRP mapping for `mydb/weekly` to determine which bucket to query.
|
||||
|
||||
_Note: The retention policy name is used only for DBRP mapping. Actual data retention is controlled by the target bucket's retention period setting, not by the retention policy name._
|
||||
|
||||
### Related
|
||||
|
||||
- [Execute InfluxQL queries using the v1 API](/influxdb3/cloud-serverless/query-data/execute-queries/influxql/api/v1-http/)
|
||||
- [Map v1 databases and retention policies to buckets in Cloud Serverless](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets)
|
||||
- [Manage DBRP mappings in Cloud Serverless](/influxdb3/cloud-serverless/admin/dbrp/)
|
||||
type: string
|
||||
q:
|
||||
description: Defines the InfluxQL query to run.
|
||||
type: string
|
||||
chunked:
|
||||
description: |
|
||||
If true, the response is divided into chunks of size `chunk_size`.
|
||||
type: boolean
|
||||
chunk_size:
|
||||
description: |
|
||||
The number of records that will go into a chunk.
|
||||
This parameter is only used if `chunked=true`.
|
||||
type: integer
|
||||
default: 10000
|
||||
epoch:
|
||||
description: |
|
||||
A unix timestamp precision.
|
||||
type: string
|
||||
enum:
|
||||
- h
|
||||
- m
|
||||
- s
|
||||
- ms
|
||||
- u
|
||||
- µ
|
||||
- ns
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: header
|
||||
name: Accept
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
||||
default: application/json
|
||||
enum:
|
||||
- application/json
|
||||
- application/csv
|
||||
- text/csv
|
||||
- application/x-msgpack
|
||||
- in: header
|
||||
name: Accept-Encoding
|
||||
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
- in: header
|
||||
name: Content-Type
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- application/vnd.influxql
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: Bucket to query.
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: q
|
||||
description: Defines the influxql query to run.
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Query results
|
||||
headers:
|
||||
Content-Encoding:
|
||||
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
Trace-Id:
|
||||
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies the request's trace ID.
|
||||
content:
|
||||
application/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
text/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLResponse'
|
||||
examples:
|
||||
influxql-chunk_size_2:
|
||||
value: |
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
|
||||
application/x-msgpack:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'429':
|
||||
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
|
||||
headers:
|
||||
Retry-After:
|
||||
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
||||
schema:
|
||||
type: integer
|
||||
format: int32
|
||||
default:
|
||||
description: Error processing query
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
components:
|
||||
parameters:
|
||||
TraceSpan:
|
||||
in: header
|
||||
name: Zap-Trace-Span
|
||||
description: OpenTracing span context
|
||||
example:
|
||||
trace_id: '1'
|
||||
span_id: '1'
|
||||
baggage:
|
||||
key: value
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
AuthUserV1:
|
||||
in: query
|
||||
name: u
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: Username.
|
||||
AuthPassV1:
|
||||
in: query
|
||||
name: p
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: User token.
|
||||
schemas:
|
||||
InfluxQLResponse:
|
||||
description: |
|
||||
The JSON response for an InfluxQL query.
|
||||
|
||||
A response contains the collection of results for a query.
|
||||
`results` is an array of resultset objects.
|
||||
|
||||
If the response is chunked, the `transfer-encoding` response header is set to `chunked` and each resultset object is sent in a separate JSON object.
|
||||
properties:
|
||||
results:
|
||||
description: |
|
||||
A resultset object that contains the `statement_id` and the `series` array.
|
||||
|
||||
Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the resultset is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
series:
|
||||
description: |
|
||||
An array of series objects--the results of the query. A series of rows shares the same group key returned from the execution of a statement.
|
||||
|
||||
If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
columns:
|
||||
description: An array of column names
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
name:
|
||||
description: The name of the series
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the series is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
tags:
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |
|
||||
A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`.
|
||||
type: object
|
||||
values:
|
||||
description: |
|
||||
An array of rows, where each row is an array of values.
|
||||
items:
|
||||
items: {}
|
||||
type: array
|
||||
type: array
|
||||
type: object
|
||||
type: array
|
||||
statement_id:
|
||||
description: |
|
||||
An integer that represents the statement's position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results.
|
||||
type: integer
|
||||
type: object
|
||||
oneOf:
|
||||
- required:
|
||||
- statement_id
|
||||
- error
|
||||
- required:
|
||||
- statement_id
|
||||
- series
|
||||
type: array
|
||||
type: object
|
||||
InfluxQLCSVResponse:
|
||||
type: string
|
||||
example: |
|
||||
name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value
|
||||
Error:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- unprocessable entity
|
||||
- empty value
|
||||
- unavailable
|
||||
- forbidden
|
||||
- too many requests
|
||||
- unauthorized
|
||||
- method not allowed
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
LineProtocolError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- empty value
|
||||
- unavailable
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
op:
|
||||
readOnly: true
|
||||
description: Op describes the logical code operation during error. Useful for debugging.
|
||||
type: string
|
||||
err:
|
||||
readOnly: true
|
||||
description: Err is a stack of errors that occurred during processing of the request. Useful for debugging.
|
||||
type: string
|
||||
line:
|
||||
readOnly: true
|
||||
description: First line within sent body containing malformed data
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- op
|
||||
- err
|
||||
LineProtocolLengthError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- invalid
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
maxLength:
|
||||
readOnly: true
|
||||
description: Max length in bytes for a body of line-protocol.
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- maxLength
|
||||
securitySchemes:
|
||||
TokenAuthentication:
|
||||
type: apiKey
|
||||
name: Authorization
|
||||
in: header
|
||||
description: |
|
||||
Use the [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
scheme to authenticate to the InfluxDB API.
|
||||
|
||||
|
||||
In your API requests, send an `Authorization` header.
|
||||
For the header value, provide the word `Token` followed by a space and an InfluxDB API token.
|
||||
The word `Token` is case-sensitive.
|
||||
|
||||
|
||||
### Syntax
|
||||
|
||||
`Authorization: Token YOUR_INFLUX_TOKEN`
|
||||
|
||||
|
||||
For examples and more information, see the following:
|
||||
- [`/authorizations`](#tag/Authorizations) endpoint.
|
||||
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
|
||||
- [Manage API tokens](/influxdb/cloud/security/tokens/).
|
||||
BasicAuthentication:
|
||||
type: http
|
||||
scheme: basic
|
||||
description: |
|
||||
Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
QuerystringAuthentication:
|
||||
type: apiKey
|
||||
in: query
|
||||
name: u=&p=
|
||||
description: |
|
||||
Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
scheme with InfluxDB 1.x API parameters to provide credentials through the query string.
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
|
|
@ -67,8 +67,6 @@ tags:
|
|||
|
||||
5. Query data using SQL or InfluxQL with a Flight client or the HTTP API.
|
||||
|
||||
For more information, see the
|
||||
[Get started](/influxdb3/clustered/get-started/) guide.
|
||||
- name: Tables
|
||||
description: Manage tables in a database
|
||||
paths:
|
||||
|
|
@ -952,7 +950,7 @@ paths:
|
|||
tags:
|
||||
- Database tokens
|
||||
description: |
|
||||
Create a [database token](/influxdb3/clustered/admin/tokens/database/) for a cluster.
|
||||
Create a database token for a cluster.
|
||||
|
||||
The token returned on the `accessToken` property in the response can be used to authenticate query and write requests to the cluster.
|
||||
|
||||
|
|
@ -965,9 +963,9 @@ paths:
|
|||
#### Store secure tokens in a secret store
|
||||
|
||||
We recommend storing database tokens in a **secure secret store**.
|
||||
For example, see how to [authenticate Telegraf using tokens in your OS secret store](https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os).
|
||||
For example, see how to authenticate Telegraf using tokens in your OS secret store.
|
||||
|
||||
If you lose a token, [delete the token from InfluxDB](/influxdb3/clustered/admin/tokens/database/delete/) and create a new one.
|
||||
If you lose a token, delete the token from InfluxDB and create a new one.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
|
|
@ -1116,7 +1114,7 @@ paths:
|
|||
parameters:
|
||||
- name: tokenId
|
||||
in: path
|
||||
description: The ID of the [database token](/influxdb3/clustered/admin/tokens/database/) to get
|
||||
description: The ID of the database token to get
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -1208,7 +1206,7 @@ paths:
|
|||
parameters:
|
||||
- name: tokenId
|
||||
in: path
|
||||
description: The ID of the [database token](/influxdb3/clustered/admin/tokens/database/) to update
|
||||
description: The ID of the database token to update
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -1380,7 +1378,7 @@ paths:
|
|||
parameters:
|
||||
- name: tokenId
|
||||
in: path
|
||||
description: The ID of the [database token](/influxdb3/clustered/admin/tokens/database/) to delete
|
||||
description: The ID of the database token to delete
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/UuidV4'
|
||||
|
|
@ -1466,7 +1464,7 @@ components:
|
|||
minimum: 1
|
||||
ClusterDatabaseRetentionPeriod:
|
||||
description: |
|
||||
The retention period of the [cluster database](/influxdb3/clustered/admin/databases/) in nanoseconds, if applicable
|
||||
The retention period of the cluster database in nanoseconds, if applicable
|
||||
|
||||
If the retention period is not set or is set to 0, the database will have infinite retention
|
||||
type: integer
|
||||
|
|
@ -1496,7 +1494,7 @@ components:
|
|||
minimum: 1
|
||||
ClusterDatabasePartitionTemplate:
|
||||
description: |
|
||||
A template for [partitioning](/influxdb3/clustered/admin/custom-partitions/) a cluster database.
|
||||
A template for partitioning a cluster database.
|
||||
|
||||
Each template part is evaluated in sequence, concatinating the final
|
||||
partition key from the output of each part, delimited by the partition
|
||||
|
|
@ -1540,7 +1538,7 @@ components:
|
|||
* `time=2023-01-01, a=<long string>` -> `2023|<long string>#|!|!`
|
||||
* `time=2023-01-01, c=<long string>` -> `2023|!|!|<bucket ID for untruncated long string>`
|
||||
|
||||
When using the default [partitioning](/influxdb3/clustered/admin/custom-partitions/) template (YYYY-MM-DD) there is no
|
||||
When using the default partitioning template (YYYY-MM-DD) there is no
|
||||
encoding necessary, as the derived partition key contains a single part, and
|
||||
no reserved characters. [`TemplatePart::Bucket`] parts by definition will
|
||||
always be within the part length limit and contain no restricted characters
|
||||
|
|
@ -1642,7 +1640,7 @@ components:
|
|||
tagName: c
|
||||
numberOfBuckets: 10
|
||||
ClusterDatabaseTableName:
|
||||
description: The name of the [cluster database](/influxdb3/clustered/admin/databases/) table
|
||||
description: The name of the cluster database table
|
||||
type: string
|
||||
examples:
|
||||
- TableOne
|
||||
|
|
@ -1655,15 +1653,15 @@ components:
|
|||
- Limited Access Token
|
||||
- Full Access Token
|
||||
DatabaseTokenResourceAllDatabases:
|
||||
description: A resource value for a [database token](/influxdb3/clustered/admin/tokens/database/) permission that refers to all databases
|
||||
description: A resource value for a database token permission that refers to all databases
|
||||
type: string
|
||||
enum:
|
||||
- '*'
|
||||
DatabaseTokenPermissionAction:
|
||||
description: The action the [database token](/influxdb3/clustered/admin/tokens/database/) permission allows
|
||||
description: The action the database token permission allows
|
||||
type: string
|
||||
DatabaseTokenPermissionResource:
|
||||
description: The resource the [database token](/influxdb3/clustered/admin/tokens/database/) permission applies to
|
||||
description: The resource the database token permission applies to
|
||||
anyOf:
|
||||
- $ref: '#/components/schemas/ClusterDatabaseName'
|
||||
- $ref: '#/components/schemas/DatabaseTokenResourceAllDatabases'
|
||||
|
|
@ -1687,7 +1685,7 @@ components:
|
|||
- action: write
|
||||
resource: '*'
|
||||
DatabaseTokenPermissions:
|
||||
description: The list of permissions the [database token](/influxdb3/clustered/admin/tokens/database/) allows
|
||||
description: The list of permissions the database token allows
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/DatabaseTokenPermission'
|
||||
|
|
@ -1700,7 +1698,7 @@ components:
|
|||
resource: '*'
|
||||
DatabaseTokenCreatedAt:
|
||||
description: |
|
||||
The date and time that the [database token](/influxdb3/clustered/admin/tokens/database/) was created
|
||||
The date and time that the database token was created
|
||||
|
||||
Uses RFC3339 format
|
||||
$ref: '#/components/schemas/DateTimeRfc3339'
|
||||
|
|
|
|||
|
|
@ -5,7 +5,11 @@ tags:
|
|||
InfluxDB 3 Clustered databases.
|
||||
x-related:
|
||||
- title: Manage database tokens
|
||||
href: /influxdb3/clustered/admin/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
|
||||
|
||||
Databases:
|
||||
description: >
|
||||
|
|
@ -14,11 +18,16 @@ tags:
|
|||
x-related:
|
||||
- title: Manage databases
|
||||
href: /influxdb3/clustered/admin/databases/
|
||||
- title: Custom partitions
|
||||
href: /influxdb3/clustered/admin/custom-partitions/
|
||||
|
||||
Quick start:
|
||||
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/
|
||||
# x-traitTag: true — informational tag, no operations
|
||||
|
||||
Tables:
|
||||
|
|
@ -28,3 +37,5 @@ tags:
|
|||
x-related:
|
||||
- title: Manage tables
|
||||
href: /influxdb3/clustered/admin/tables/
|
||||
- title: Custom partitions
|
||||
href: /influxdb3/clustered/admin/custom-partitions/
|
||||
|
|
|
|||
|
|
@ -1,21 +0,0 @@
|
|||
title: InfluxDB v1 HTTP API for InfluxDB 3 Clustered
|
||||
x-influxdata-short-title: v1 Compatibility API
|
||||
x-influxdata-short-description: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
|
||||
description: |
|
||||
The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
|
||||
|
||||
The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
|
||||
#### Related
|
||||
|
||||
[InfluxDB `/api/v2` API for InfluxDB 3 Clustered](/influxdb3/clustered/api/v2/)
|
||||
license:
|
||||
name: MIT
|
||||
url: 'https://opensource.org/licenses/MIT'
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
|
|
@ -1,659 +0,0 @@
|
|||
openapi: 3.0.0
|
||||
info:
|
||||
title: InfluxDB v1 HTTP API for InfluxDB 3 Clustered
|
||||
version: ''
|
||||
description: |
|
||||
The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
|
||||
|
||||
The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
||||
|
||||
This documentation is generated from the
|
||||
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
||||
|
||||
#### Related
|
||||
|
||||
[InfluxDB `/api/v2` API for InfluxDB 3 Clustered](/influxdb3/clustered/api/v2/)
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
contact:
|
||||
name: InfluxData
|
||||
url: https://www.influxdata.com
|
||||
email: support@influxdata.com
|
||||
servers:
|
||||
- url: /
|
||||
security:
|
||||
- TokenAuthentication: []
|
||||
- BasicAuthentication: []
|
||||
- QuerystringAuthentication: []
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: |
|
||||
The InfluxDB 1.x API requires authentication for all requests.
|
||||
InfluxDB Cloud uses InfluxDB API tokens to authenticate requests.
|
||||
|
||||
|
||||
For more information, see the following:
|
||||
- [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
|
||||
<!-- ReDoc-Inject: <security-definitions> -->
|
||||
x-traitTag: true
|
||||
- name: Query
|
||||
- name: Write
|
||||
paths:
|
||||
/write:
|
||||
post:
|
||||
operationId: PostWriteV1
|
||||
tags:
|
||||
- Write
|
||||
summary: Write time series data into InfluxDB in a V1-compatible format
|
||||
requestBody:
|
||||
description: Line protocol body
|
||||
required: true
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: |
|
||||
The database to write to.
|
||||
|
||||
**Database targeting:** In InfluxDB Clustered, databases can be named using the `database_name/retention_policy_name` convention for InfluxQL compatibility. InfluxDB Clustered does not use DBRP mappings. The db and rp parameters are used to construct the target database name following this naming convention.
|
||||
|
||||
**Auto-creation behavior:** InfluxDB Clustered requires databases to be created before writing data. The v1 `/write` API does not automatically create databases. If the specified
|
||||
database does not exist, the write request will fail.
|
||||
|
||||
Authentication: Requires a valid API token with _write_ permissions for the target database.
|
||||
|
||||
### Related
|
||||
|
||||
- [Write data to InfluxDB Clustered](/influxdb3/clustered/write-data/)
|
||||
- [Use the InfluxDB v1 API with InfluxDB Clustered](/influxdb3/clustered/guides/api-compatibility/v1/)
|
||||
- [Manage databases in InfluxDB Clustered](/influxdb3/clustered/admin/databases/)
|
||||
- [InfluxQL DBRP naming convention in InfluxDB Clustered](/influxdb3/clustered/admin/databases/create/#influxql-dbrp-naming-convention)
|
||||
- [Migrate data from InfluxDB v1 to InfluxDB Clustered](/influxdb3/clustered/guides/migrate-data/migrate-1x-to-clustered/)
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: precision
|
||||
schema:
|
||||
type: string
|
||||
description: Write precision.
|
||||
- in: header
|
||||
name: Content-Encoding
|
||||
description: When present, its value indicates to the database that compression is applied to the line protocol body.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
responses:
|
||||
'204':
|
||||
description: Write data is correctly formatted and accepted for writing to the bucket.
|
||||
'400':
|
||||
description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolError'
|
||||
'401':
|
||||
description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'403':
|
||||
description: No token was sent and they are required.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
'413':
|
||||
description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LineProtocolLengthError'
|
||||
'429':
|
||||
description: Token is temporarily over quota or ingesters are resource constrained.
|
||||
'503':
|
||||
description: Server is temporarily unavailable to accept writes due to too many concurrent requests or insufficient healthy ingesters.
|
||||
default:
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/query:
|
||||
get:
|
||||
operationId: GetQueryV1
|
||||
tags:
|
||||
- Query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: header
|
||||
name: Accept
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
||||
default: application/json
|
||||
enum:
|
||||
- application/json
|
||||
- application/csv
|
||||
- text/csv
|
||||
- application/x-msgpack
|
||||
- in: header
|
||||
name: Accept-Encoding
|
||||
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
- in: query
|
||||
name: chunked
|
||||
description: |
|
||||
If true, the response is divided into chunks of size `chunk_size`.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
- in: query
|
||||
name: chunk_size
|
||||
description: |
|
||||
The number of records that will go into a chunk.
|
||||
This parameter is only used if `chunked=true`.
|
||||
schema:
|
||||
type: integer
|
||||
default: 10000
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: The database to query from.
|
||||
- in: query
|
||||
name: pretty
|
||||
description: |
|
||||
If true, the JSON response is formatted in a human-readable format.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
- in: query
|
||||
name: q
|
||||
description: Defines the InfluxQL query to run.
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- name: epoch
|
||||
description: |
|
||||
Formats timestamps as unix (epoch) timestamps with the specified precision
|
||||
instead of RFC3339 timestamps with nanosecond precision.
|
||||
in: query
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- h
|
||||
- m
|
||||
- s
|
||||
- ms
|
||||
- u
|
||||
- µ
|
||||
- ns
|
||||
responses:
|
||||
'200':
|
||||
description: Query results
|
||||
headers:
|
||||
Content-Encoding:
|
||||
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
Trace-Id:
|
||||
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies the request's trace ID.
|
||||
content:
|
||||
application/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
text/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLResponse'
|
||||
examples:
|
||||
influxql-chunk_size_2:
|
||||
value: |
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
|
||||
application/x-msgpack:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'429':
|
||||
description: Token is temporarily over quota or the querier is resource constrained.
|
||||
default:
|
||||
description: Error processing query
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
post:
|
||||
operationId: PostQueryV1
|
||||
tags:
|
||||
- Query
|
||||
summary: Query using the InfluxDB v1 HTTP API
|
||||
requestBody:
|
||||
description: InfluxQL query to execute.
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
db:
|
||||
type: string
|
||||
description: Database to query.
|
||||
rp:
|
||||
description: |
|
||||
The retention policy name for InfluxQL compatibility
|
||||
|
||||
Optional parameter that, when combined with the db parameter, forms the complete database name to query. In InfluxDB Clustered, databases can be named using the
|
||||
database_name/retention_policy_name convention for InfluxQL compatibility.
|
||||
|
||||
When a request specifies both `db` and `rp`, InfluxDB Clustered combines them as `db/rp` to target the database--for example:
|
||||
|
||||
- If `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`
|
||||
- If only `db=mydb` is provided (no `rp`), the query targets the database named `mydb`
|
||||
|
||||
Unlike InfluxDB v1 and Cloud Serverless, InfluxDB Clustered does not use DBRP mappings or separate retention policy objects. This parameter exists solely for v1 API
|
||||
compatibility and database naming conventions.
|
||||
|
||||
Note: The retention policy name does not control data retention in InfluxDB Clustered. Data retention is determined by the database's _retention period_ setting.
|
||||
|
||||
### Related
|
||||
|
||||
- [Use the v1 query API and InfluxQL to query data in InfluxDB Clustered](/influxdb3/clustered/query-data/execute-queries/influxdb-v1-api/)
|
||||
- [Use the InfluxDB v1 API with InfluxDB Clustered](/influxdb3/clustered/guides/api-compatibility/v1/)
|
||||
- [Manage databases in InfluxDB Clustered](/influxdb3/clustered/admin/databases/)
|
||||
- [InfluxQL DBRP naming convention in InfluxDB Clustered](/influxdb3/clustered/admin/databases/create/#influxql-dbrp-naming-convention)
|
||||
- [Migrate data from InfluxDB v1 to InfluxDB Clustered](/influxdb3/clustered/guides/migrate-data/migrate-1x-to-clustered/)
|
||||
type: string
|
||||
q:
|
||||
description: |
|
||||
Defines the InfluxQL query to run.
|
||||
type: string
|
||||
chunked:
|
||||
description: |
|
||||
If true, the response is divided into chunks of size `chunk_size`.
|
||||
type: boolean
|
||||
chunk_size:
|
||||
description: |
|
||||
The number of records that will go into a chunk.
|
||||
This parameter is only used if `chunked=true`.
|
||||
type: integer
|
||||
default: 10000
|
||||
epoch:
|
||||
description: |
|
||||
A unix timestamp precision.
|
||||
type: string
|
||||
enum:
|
||||
- h
|
||||
- m
|
||||
- s
|
||||
- ms
|
||||
- u
|
||||
- µ
|
||||
- ns
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TraceSpan'
|
||||
- $ref: '#/components/parameters/AuthUserV1'
|
||||
- $ref: '#/components/parameters/AuthPassV1'
|
||||
- in: header
|
||||
name: Accept
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
||||
default: application/json
|
||||
enum:
|
||||
- application/json
|
||||
- application/csv
|
||||
- text/csv
|
||||
- application/x-msgpack
|
||||
- in: header
|
||||
name: Accept-Encoding
|
||||
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
- in: header
|
||||
name: Content-Type
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- application/vnd.influxql
|
||||
- in: query
|
||||
name: db
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
description: Bucket to query.
|
||||
- in: query
|
||||
name: rp
|
||||
schema:
|
||||
type: string
|
||||
description: Retention policy name.
|
||||
- in: query
|
||||
name: q
|
||||
description: Defines the influxql query to run.
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Query results
|
||||
headers:
|
||||
Content-Encoding:
|
||||
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
||||
default: identity
|
||||
enum:
|
||||
- gzip
|
||||
- identity
|
||||
Trace-Id:
|
||||
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
||||
schema:
|
||||
type: string
|
||||
description: Specifies the request's trace ID.
|
||||
content:
|
||||
application/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
text/csv:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/InfluxQLResponse'
|
||||
examples:
|
||||
influxql-chunk_size_2:
|
||||
value: |
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
|
||||
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
|
||||
application/x-msgpack:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'429':
|
||||
description: Token is temporarily over quota or queriers are resource constrained.
|
||||
default:
|
||||
description: Error processing query
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
components:
|
||||
parameters:
|
||||
TraceSpan:
|
||||
in: header
|
||||
name: Zap-Trace-Span
|
||||
description: OpenTracing span context
|
||||
example:
|
||||
trace_id: '1'
|
||||
span_id: '1'
|
||||
baggage:
|
||||
key: value
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
AuthUserV1:
|
||||
in: query
|
||||
name: u
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: Username.
|
||||
AuthPassV1:
|
||||
in: query
|
||||
name: p
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
description: User token.
|
||||
schemas:
|
||||
InfluxQLResponse:
|
||||
description: |
|
||||
The JSON response for an InfluxQL query.
|
||||
|
||||
A response contains the collection of results for a query.
|
||||
`results` is an array of resultset objects.
|
||||
|
||||
If the response is chunked, the `transfer-encoding` response header is set to `chunked` and each resultset object is sent in a separate JSON object.
|
||||
properties:
|
||||
results:
|
||||
description: |
|
||||
A resultset object that contains the `statement_id` and the `series` array.
|
||||
|
||||
Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the resultset is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
series:
|
||||
description: |
|
||||
An array of series objects--the results of the query. A series of rows shares the same group key returned from the execution of a statement.
|
||||
|
||||
If a property is not present, it is assumed to be `null`.
|
||||
items:
|
||||
properties:
|
||||
columns:
|
||||
description: An array of column names
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
name:
|
||||
description: The name of the series
|
||||
type: string
|
||||
partial:
|
||||
description: |
|
||||
True if the series is not complete--the response data is chunked; otherwise, false or omitted.
|
||||
type: boolean
|
||||
tags:
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |
|
||||
A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`.
|
||||
type: object
|
||||
values:
|
||||
description: |
|
||||
An array of rows, where each row is an array of values.
|
||||
items:
|
||||
items: {}
|
||||
type: array
|
||||
type: array
|
||||
type: object
|
||||
type: array
|
||||
statement_id:
|
||||
description: |
|
||||
An integer that represents the statement's position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results.
|
||||
type: integer
|
||||
type: object
|
||||
oneOf:
|
||||
- required:
|
||||
- statement_id
|
||||
- error
|
||||
- required:
|
||||
- statement_id
|
||||
- series
|
||||
type: array
|
||||
type: object
|
||||
InfluxQLCSVResponse:
|
||||
type: string
|
||||
example: |
|
||||
name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value
|
||||
Error:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- unprocessable entity
|
||||
- empty value
|
||||
- unavailable
|
||||
- forbidden
|
||||
- too many requests
|
||||
- unauthorized
|
||||
- method not allowed
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
LineProtocolError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- internal error
|
||||
- not found
|
||||
- conflict
|
||||
- invalid
|
||||
- empty value
|
||||
- unavailable
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
op:
|
||||
readOnly: true
|
||||
description: Op describes the logical code operation during error. Useful for debugging.
|
||||
type: string
|
||||
err:
|
||||
readOnly: true
|
||||
description: Err is a stack of errors that occurred during processing of the request. Useful for debugging.
|
||||
type: string
|
||||
line:
|
||||
readOnly: true
|
||||
description: First line within sent body containing malformed data
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- op
|
||||
- err
|
||||
LineProtocolLengthError:
|
||||
properties:
|
||||
code:
|
||||
description: Code is the machine-readable error code.
|
||||
readOnly: true
|
||||
type: string
|
||||
enum:
|
||||
- invalid
|
||||
message:
|
||||
readOnly: true
|
||||
description: Message is a human-readable message.
|
||||
type: string
|
||||
maxLength:
|
||||
readOnly: true
|
||||
description: Max length in bytes for a body of line-protocol.
|
||||
type: integer
|
||||
format: int32
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
- maxLength
|
||||
securitySchemes:
|
||||
TokenAuthentication:
|
||||
type: apiKey
|
||||
name: Authorization
|
||||
in: header
|
||||
description: |
|
||||
Use the [Token authentication](#section/Authentication/TokenAuthentication)
|
||||
scheme to authenticate to the InfluxDB API.
|
||||
|
||||
|
||||
In your API requests, send an `Authorization` header.
|
||||
For the header value, provide the word `Token` followed by a space and an InfluxDB API token.
|
||||
The word `Token` is case-sensitive.
|
||||
|
||||
|
||||
### Syntax
|
||||
|
||||
`Authorization: Token YOUR_INFLUX_TOKEN`
|
||||
|
||||
|
||||
For examples and more information, see the following:
|
||||
- [`/authorizations`](#tag/Authorizations) endpoint.
|
||||
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
|
||||
- [Manage API tokens](/influxdb/cloud/security/tokens/).
|
||||
BasicAuthentication:
|
||||
type: http
|
||||
scheme: basic
|
||||
description: |
|
||||
Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication)
|
||||
scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
QuerystringAuthentication:
|
||||
type: apiKey
|
||||
in: query
|
||||
name: u=&p=
|
||||
description: |
|
||||
Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
||||
scheme with InfluxDB 1.x API parameters to provide credentials through the query string.
|
||||
|
||||
|
||||
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
||||
|
|
@ -917,7 +917,12 @@ const productConfigs: ProductConfigMap = {
|
|||
// These have existing /reference/api/ pages with menu entries,
|
||||
// so we skip adding menu entries to the generated parent pages.
|
||||
'cloud-v2': {
|
||||
specFile: path.join(API_DOCS_ROOT, 'influxdb/cloud/v2/ref.yml'),
|
||||
specFiles: [
|
||||
{
|
||||
path: path.join(API_DOCS_ROOT, 'influxdb/cloud/influxdb-cloud-v2-openapi.yaml'),
|
||||
displayName: 'API',
|
||||
},
|
||||
],
|
||||
pagesDir: path.join(DOCS_ROOT, 'content/influxdb/cloud'),
|
||||
description: 'InfluxDB Cloud (v2 API)',
|
||||
menuKey: 'influxdb_cloud',
|
||||
|
|
@ -925,7 +930,12 @@ const productConfigs: ProductConfigMap = {
|
|||
useTagBasedGeneration: true,
|
||||
},
|
||||
'oss-v2': {
|
||||
specFile: path.join(API_DOCS_ROOT, 'influxdb/v2/v2/ref.yml'),
|
||||
specFiles: [
|
||||
{
|
||||
path: path.join(API_DOCS_ROOT, 'influxdb/v2/influxdb-oss-v2-openapi.yaml'),
|
||||
displayName: 'API',
|
||||
},
|
||||
],
|
||||
pagesDir: path.join(DOCS_ROOT, 'content/influxdb/v2'),
|
||||
description: 'InfluxDB OSS v2',
|
||||
menuKey: 'influxdb_v2',
|
||||
|
|
@ -976,7 +986,12 @@ const productConfigs: ProductConfigMap = {
|
|||
useTagBasedGeneration: true,
|
||||
},
|
||||
'cloud-serverless': {
|
||||
specFile: path.join(API_DOCS_ROOT, 'influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml'),
|
||||
specFiles: [
|
||||
{
|
||||
path: path.join(API_DOCS_ROOT, 'influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml'),
|
||||
displayName: 'v2 Data API',
|
||||
},
|
||||
],
|
||||
pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/cloud-serverless'),
|
||||
description: 'InfluxDB Cloud Serverless',
|
||||
menuKey: 'influxdb3_cloud_serverless',
|
||||
|
|
@ -1036,7 +1051,7 @@ const LINK_PATTERN = /\/influxdb\/version\//g;
|
|||
* @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/influxdb/v2/v2/ref.yml' → '/influxdb/v2'
|
||||
* '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'
|
||||
*/
|
||||
|
|
@ -1202,10 +1217,19 @@ function processSpecFile(
|
|||
return null;
|
||||
}
|
||||
|
||||
// Generate filename from display name or use default
|
||||
const specSlug = specConfig.displayName
|
||||
? slugifyDisplayName(specConfig.displayName)
|
||||
: path.parse(specConfig.path).name;
|
||||
// Generate filename from display name or use default.
|
||||
// Strip staticDirName prefix from the spec filename to avoid doubled names
|
||||
// (e.g., influxdb3-core + influxdb3-core-openapi → influxdb3-core-openapi).
|
||||
let specSlug: string;
|
||||
if (specConfig.displayName) {
|
||||
specSlug = slugifyDisplayName(specConfig.displayName);
|
||||
} else {
|
||||
const rawName = path.parse(specConfig.path).name;
|
||||
const prefix = `${staticDirName}-`;
|
||||
specSlug = rawName.startsWith(prefix)
|
||||
? rawName.slice(prefix.length)
|
||||
: rawName;
|
||||
}
|
||||
|
||||
const staticSpecPath = path.join(
|
||||
staticPath,
|
||||
|
|
|
|||
|
|
@ -83,7 +83,10 @@ interface OpenApiSpec {
|
|||
info?: OpenApiInfo;
|
||||
servers?: OpenApiServer[];
|
||||
tags?: OpenApiTag[];
|
||||
paths?: Record<string, Record<string, { tags?: string[]; [k: string]: unknown }>>;
|
||||
paths?: Record<
|
||||
string,
|
||||
Record<string, { tags?: string[]; [k: string]: unknown }>
|
||||
>;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
|
|
@ -148,7 +151,7 @@ function log(msg: string): void {
|
|||
function resolveContentFile(
|
||||
filename: string,
|
||||
specDir: string,
|
||||
productAbsDir: string,
|
||||
productAbsDir: string
|
||||
): string | null {
|
||||
// API-specific: {specDir}/content/{filename}
|
||||
const apiSpecific = path.join(specDir, 'content', filename);
|
||||
|
|
@ -171,7 +174,7 @@ function applyInfoOverlay(
|
|||
spec: OpenApiSpec,
|
||||
specDir: string,
|
||||
productAbsDir: string,
|
||||
label: string,
|
||||
label: string
|
||||
): boolean {
|
||||
const infoPath = resolveContentFile('info.yml', specDir, productAbsDir);
|
||||
if (!infoPath) return false;
|
||||
|
|
@ -188,7 +191,9 @@ function applyInfoOverlay(
|
|||
}
|
||||
|
||||
if (applied > 0) {
|
||||
log(`${label}: applied ${applied} info field(s) from ${path.relative(productAbsDir, infoPath)}`);
|
||||
log(
|
||||
`${label}: applied ${applied} info field(s) from ${path.relative(productAbsDir, infoPath)}`
|
||||
);
|
||||
}
|
||||
return applied > 0;
|
||||
}
|
||||
|
|
@ -202,7 +207,7 @@ function applyServersOverlay(
|
|||
spec: OpenApiSpec,
|
||||
specDir: string,
|
||||
productAbsDir: string,
|
||||
label: string,
|
||||
label: string
|
||||
): boolean {
|
||||
const serversPath = resolveContentFile('servers.yml', specDir, productAbsDir);
|
||||
if (!serversPath) return false;
|
||||
|
|
@ -211,7 +216,9 @@ function applyServersOverlay(
|
|||
if (!servers || !Array.isArray(servers)) return false;
|
||||
|
||||
spec.servers = servers;
|
||||
log(`${label}: applied ${servers.length} server(s) from ${path.relative(productAbsDir, serversPath)}`);
|
||||
log(
|
||||
`${label}: applied ${servers.length} server(s) from ${path.relative(productAbsDir, serversPath)}`
|
||||
);
|
||||
return true;
|
||||
}
|
||||
|
||||
|
|
@ -226,7 +233,11 @@ function collectOperationTags(spec: OpenApiSpec): Set<string> {
|
|||
const found = new Set<string>();
|
||||
for (const pathItem of Object.values(spec.paths ?? {})) {
|
||||
for (const operation of Object.values(pathItem)) {
|
||||
if (operation && typeof operation === 'object' && Array.isArray(operation.tags)) {
|
||||
if (
|
||||
operation &&
|
||||
typeof operation === 'object' &&
|
||||
Array.isArray(operation.tags)
|
||||
) {
|
||||
for (const t of operation.tags) found.add(t as string);
|
||||
}
|
||||
}
|
||||
|
|
@ -243,8 +254,14 @@ function renameTag(spec: OpenApiSpec, oldName: string, newName: string): void {
|
|||
}
|
||||
for (const pathItem of Object.values(spec.paths ?? {})) {
|
||||
for (const operation of Object.values(pathItem)) {
|
||||
if (operation && typeof operation === 'object' && Array.isArray(operation.tags)) {
|
||||
operation.tags = operation.tags.map((t: string) => (t === oldName ? newName : t));
|
||||
if (
|
||||
operation &&
|
||||
typeof operation === 'object' &&
|
||||
Array.isArray(operation.tags)
|
||||
) {
|
||||
operation.tags = operation.tags.map((t: string) =>
|
||||
t === oldName ? newName : t
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -258,7 +275,7 @@ function renameTag(spec: OpenApiSpec, oldName: string, newName: string): void {
|
|||
function applyTagConfig(
|
||||
spec: OpenApiSpec,
|
||||
tagConfigPath: string,
|
||||
label: string,
|
||||
label: string
|
||||
): boolean {
|
||||
const tagsCfg = loadYaml<TagsYml>(tagConfigPath);
|
||||
if (!tagsCfg || !tagsCfg.tags) {
|
||||
|
|
@ -303,7 +320,8 @@ function applyTagConfig(
|
|||
spec.tags!.push(tagObj);
|
||||
}
|
||||
|
||||
if (cfg.description !== undefined) tagObj.description = cfg.description.trim();
|
||||
if (cfg.description !== undefined)
|
||||
tagObj.description = cfg.description.trim();
|
||||
if (cfg['x-related'] !== undefined) tagObj['x-related'] = cfg['x-related'];
|
||||
}
|
||||
|
||||
|
|
@ -349,8 +367,10 @@ function processProduct(apiDocsRoot: string, productDir: string): void {
|
|||
|
||||
// Apply all transforms
|
||||
let modified = false;
|
||||
modified = applyInfoOverlay(spec, specDir, productAbsDir, label) || modified;
|
||||
modified = applyServersOverlay(spec, specDir, productAbsDir, label) || modified;
|
||||
modified =
|
||||
applyInfoOverlay(spec, specDir, productAbsDir, label) || modified;
|
||||
modified =
|
||||
applyServersOverlay(spec, specDir, productAbsDir, label) || modified;
|
||||
|
||||
const tagConfigPath = path.join(specDir, 'tags.yml');
|
||||
if (fs.existsSync(tagConfigPath)) {
|
||||
|
|
|
|||
|
|
@ -39,14 +39,17 @@ interface OpenApiSpec {
|
|||
info: { title: string; version: string; [k: string]: unknown };
|
||||
servers?: Array<{ url: string; [k: string]: unknown }>;
|
||||
tags?: OpenApiTag[];
|
||||
paths?: Record<string, Record<string, { tags?: string[]; [k: string]: unknown }>>;
|
||||
paths?: Record<
|
||||
string,
|
||||
Record<string, { tags?: string[]; [k: string]: unknown }>
|
||||
>;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
function makeSpec(
|
||||
tags: OpenApiTag[],
|
||||
operationTags: string[],
|
||||
overrides?: Partial<OpenApiSpec>,
|
||||
overrides?: Partial<OpenApiSpec>
|
||||
): OpenApiSpec {
|
||||
return {
|
||||
openapi: '3.0.0',
|
||||
|
|
@ -65,7 +68,12 @@ function makeSpec(
|
|||
};
|
||||
}
|
||||
|
||||
function createTmpRoot(): { root: string; productDir: string; specDir: string; specPath: string } {
|
||||
function createTmpRoot(): {
|
||||
root: string;
|
||||
productDir: string;
|
||||
specDir: string;
|
||||
specPath: string;
|
||||
} {
|
||||
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'post-process-test-'));
|
||||
const productDir = path.join(root, 'influxdb3', 'core');
|
||||
const specDir = path.join(productDir, 'v3');
|
||||
|
|
@ -188,15 +196,25 @@ function testTagRename(): void {
|
|||
|
||||
const spec = readYaml<OpenApiSpec>(specPath);
|
||||
const oldTag = spec.tags?.find((t) => t.name === 'Cache data');
|
||||
assert('2b. old tag name gone from tags[]', !oldTag, 'old tag still present in tags[]');
|
||||
assert(
|
||||
'2b. old tag name gone from tags[]',
|
||||
!oldTag,
|
||||
'old tag still present in tags[]'
|
||||
);
|
||||
|
||||
const newTag = spec.tags?.find((t) => t.name === 'Cache distinct values');
|
||||
assert('2c. new tag name in tags[]', !!newTag, 'renamed tag not found in tags[]');
|
||||
assert(
|
||||
'2c. new tag name in tags[]',
|
||||
!!newTag,
|
||||
'renamed tag not found in tags[]'
|
||||
);
|
||||
|
||||
const opTags = (spec.paths?.['/test']?.['get'] as { tags?: string[] })?.tags ?? [];
|
||||
const opTags =
|
||||
(spec.paths?.['/test']?.['get'] as { tags?: string[] })?.tags ?? [];
|
||||
assert(
|
||||
'2d. operation.tags[] updated',
|
||||
opTags.includes('Cache distinct values') && !opTags.includes('Cache data'),
|
||||
opTags.includes('Cache distinct values') &&
|
||||
!opTags.includes('Cache data'),
|
||||
`operation tags: ${JSON.stringify(opTags)}`
|
||||
);
|
||||
} finally {
|
||||
|
|
@ -212,7 +230,9 @@ function testXRelated(): void {
|
|||
tags: {
|
||||
'Write data': {
|
||||
description: 'Write data.',
|
||||
'x-related': [{ title: 'Write data guide', href: '/influxdb3/core/write-data/' }],
|
||||
'x-related': [
|
||||
{ title: 'Write data guide', href: '/influxdb3/core/write-data/' },
|
||||
],
|
||||
},
|
||||
},
|
||||
});
|
||||
|
|
@ -222,11 +242,18 @@ function testXRelated(): void {
|
|||
|
||||
const spec = readYaml<OpenApiSpec>(specPath);
|
||||
const tag = spec.tags?.find((t) => t.name === 'Write data');
|
||||
const related = tag?.['x-related'] as Array<{ title: string; href: string }> | undefined;
|
||||
assert('3b. x-related present', Array.isArray(related) && related.length === 1, `x-related: ${JSON.stringify(related)}`);
|
||||
const related = tag?.['x-related'] as
|
||||
| Array<{ title: string; href: string }>
|
||||
| undefined;
|
||||
assert(
|
||||
'3b. x-related present',
|
||||
Array.isArray(related) && related.length === 1,
|
||||
`x-related: ${JSON.stringify(related)}`
|
||||
);
|
||||
assert(
|
||||
'3c. x-related entry correct',
|
||||
related?.[0]?.title === 'Write data guide' && related?.[0]?.href === '/influxdb3/core/write-data/',
|
||||
related?.[0]?.title === 'Write data guide' &&
|
||||
related?.[0]?.href === '/influxdb3/core/write-data/',
|
||||
`entry: ${JSON.stringify(related?.[0])}`
|
||||
);
|
||||
} finally {
|
||||
|
|
@ -246,7 +273,11 @@ function testStaleConfigWarning(): void {
|
|||
});
|
||||
|
||||
const { stderr, exitCode } = runScript(root, 'influxdb3/core');
|
||||
assert('4a. exits 0 (warnings are not errors)', exitCode === 0, `exit code was ${exitCode}`);
|
||||
assert(
|
||||
'4a. exits 0 (warnings are not errors)',
|
||||
exitCode === 0,
|
||||
`exit code was ${exitCode}`
|
||||
);
|
||||
assert(
|
||||
'4b. stale config warning emitted',
|
||||
stderr.includes("config tag 'Ghost tag' not found in spec operations"),
|
||||
|
|
@ -262,7 +293,10 @@ function testUncoveredTagWarning(): void {
|
|||
try {
|
||||
writeYaml(
|
||||
specPath,
|
||||
makeSpec([{ name: 'Write data' }, { name: 'Query data' }], ['Write data', 'Query data'])
|
||||
makeSpec(
|
||||
[{ name: 'Write data' }, { name: 'Query data' }],
|
||||
['Write data', 'Query data']
|
||||
)
|
||||
);
|
||||
writeYaml(path.join(specDir, 'tags.yml'), {
|
||||
tags: {
|
||||
|
|
@ -271,7 +305,11 @@ function testUncoveredTagWarning(): void {
|
|||
});
|
||||
|
||||
const { stderr, exitCode } = runScript(root, 'influxdb3/core');
|
||||
assert('5a. exits 0 (warnings are not errors)', exitCode === 0, `exit code was ${exitCode}`);
|
||||
assert(
|
||||
'5a. exits 0 (warnings are not errors)',
|
||||
exitCode === 0,
|
||||
`exit code was ${exitCode}`
|
||||
);
|
||||
assert(
|
||||
'5b. uncovered tag warning emitted',
|
||||
stderr.includes("spec tag 'Query data' has no config entry in tags.yml"),
|
||||
|
|
@ -310,7 +348,11 @@ function testMalformedYamlFails(): void {
|
|||
);
|
||||
|
||||
const { exitCode } = runScript(root, 'influxdb3/core');
|
||||
assert('7a. exits 1 on malformed YAML', exitCode === 1, `exit code was ${exitCode}`);
|
||||
assert(
|
||||
'7a. exits 1 on malformed YAML',
|
||||
exitCode === 1,
|
||||
`exit code was ${exitCode}`
|
||||
);
|
||||
} finally {
|
||||
cleanup(root);
|
||||
}
|
||||
|
|
@ -324,9 +366,12 @@ function testMalformedYamlFails(): void {
|
|||
function testInfoOverlay(): void {
|
||||
const { root, specDir, specPath } = createTmpRoot();
|
||||
try {
|
||||
writeYaml(specPath, makeSpec([], [], {
|
||||
info: { title: 'Original Title', version: '0.0.0' },
|
||||
}));
|
||||
writeYaml(
|
||||
specPath,
|
||||
makeSpec([], [], {
|
||||
info: { title: 'Original Title', version: '0.0.0' },
|
||||
})
|
||||
);
|
||||
|
||||
// Create API-specific content/info.yml
|
||||
const contentDir = path.join(specDir, 'content');
|
||||
|
|
@ -341,11 +386,20 @@ function testInfoOverlay(): void {
|
|||
assert('8a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
|
||||
|
||||
const spec = readYaml<OpenApiSpec>(specPath);
|
||||
assert('8b. title overridden', spec.info.title === 'Overridden Title', `title: ${spec.info.title}`);
|
||||
assert('8c. version overridden', spec.info.version === '2.0.0', `version: ${spec.info.version}`);
|
||||
assert(
|
||||
'8b. title overridden',
|
||||
spec.info.title === 'Overridden Title',
|
||||
`title: ${spec.info.title}`
|
||||
);
|
||||
assert(
|
||||
'8c. version overridden',
|
||||
spec.info.version === '2.0.0',
|
||||
`version: ${spec.info.version}`
|
||||
);
|
||||
assert(
|
||||
'8d. x-influxdata-short-title applied',
|
||||
(spec.info as Record<string, unknown>)['x-influxdata-short-title'] === 'Short',
|
||||
(spec.info as Record<string, unknown>)['x-influxdata-short-title'] ===
|
||||
'Short',
|
||||
`x-influxdata-short-title: ${(spec.info as Record<string, unknown>)['x-influxdata-short-title']}`
|
||||
);
|
||||
} finally {
|
||||
|
|
@ -357,9 +411,12 @@ function testInfoOverlay(): void {
|
|||
function testInfoOverlayProductFallback(): void {
|
||||
const { root, productDir, specPath } = createTmpRoot();
|
||||
try {
|
||||
writeYaml(specPath, makeSpec([], [], {
|
||||
info: { title: 'Original', version: '1.0.0' },
|
||||
}));
|
||||
writeYaml(
|
||||
specPath,
|
||||
makeSpec([], [], {
|
||||
info: { title: 'Original', version: '1.0.0' },
|
||||
})
|
||||
);
|
||||
|
||||
// Create product-level content/info.yml (NOT in specDir/content/)
|
||||
const contentDir = path.join(productDir, 'content');
|
||||
|
|
@ -372,8 +429,16 @@ function testInfoOverlayProductFallback(): void {
|
|||
assert('9a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
|
||||
|
||||
const spec = readYaml<OpenApiSpec>(specPath);
|
||||
assert('9b. title from product-level', spec.info.title === 'Product-Level Title', `title: ${spec.info.title}`);
|
||||
assert('9c. version preserved', spec.info.version === '1.0.0', `version: ${spec.info.version}`);
|
||||
assert(
|
||||
'9b. title from product-level',
|
||||
spec.info.title === 'Product-Level Title',
|
||||
`title: ${spec.info.title}`
|
||||
);
|
||||
assert(
|
||||
'9c. version preserved',
|
||||
spec.info.version === '1.0.0',
|
||||
`version: ${spec.info.version}`
|
||||
);
|
||||
} finally {
|
||||
cleanup(root);
|
||||
}
|
||||
|
|
@ -383,9 +448,12 @@ function testInfoOverlayProductFallback(): void {
|
|||
function testServersOverlay(): void {
|
||||
const { root, specDir, specPath } = createTmpRoot();
|
||||
try {
|
||||
writeYaml(specPath, makeSpec([], [], {
|
||||
servers: [{ url: 'https://old.example.com' }],
|
||||
}));
|
||||
writeYaml(
|
||||
specPath,
|
||||
makeSpec([], [], {
|
||||
servers: [{ url: 'https://old.example.com' }],
|
||||
})
|
||||
);
|
||||
|
||||
const contentDir = path.join(specDir, 'content');
|
||||
fs.mkdirSync(contentDir, { recursive: true });
|
||||
|
|
@ -407,7 +475,11 @@ function testServersOverlay(): void {
|
|||
assert('10a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
|
||||
|
||||
const spec = readYaml<OpenApiSpec>(specPath);
|
||||
assert('10b. servers replaced', spec.servers?.length === 1, `server count: ${spec.servers?.length}`);
|
||||
assert(
|
||||
'10b. servers replaced',
|
||||
spec.servers?.length === 1,
|
||||
`server count: ${spec.servers?.length}`
|
||||
);
|
||||
assert(
|
||||
'10c. server URL correct',
|
||||
spec.servers?.[0]?.url === 'https://{baseurl}',
|
||||
|
|
@ -427,14 +499,17 @@ function testServersOverlay(): void {
|
|||
function testInfoOverlayPreservesFields(): void {
|
||||
const { root, specDir, specPath } = createTmpRoot();
|
||||
try {
|
||||
writeYaml(specPath, makeSpec([], [], {
|
||||
info: {
|
||||
title: 'Original Title',
|
||||
version: '3.0.0',
|
||||
description: 'Original description.',
|
||||
license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' },
|
||||
},
|
||||
}));
|
||||
writeYaml(
|
||||
specPath,
|
||||
makeSpec([], [], {
|
||||
info: {
|
||||
title: 'Original Title',
|
||||
version: '3.0.0',
|
||||
description: 'Original description.',
|
||||
license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' },
|
||||
},
|
||||
})
|
||||
);
|
||||
|
||||
const contentDir = path.join(specDir, 'content');
|
||||
fs.mkdirSync(contentDir, { recursive: true });
|
||||
|
|
@ -447,12 +522,25 @@ function testInfoOverlayPreservesFields(): void {
|
|||
assert('11a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
|
||||
|
||||
const spec = readYaml<OpenApiSpec>(specPath);
|
||||
assert('11b. title preserved', spec.info.title === 'Original Title', `title: ${spec.info.title}`);
|
||||
assert('11c. version preserved', spec.info.version === '3.0.0', `version: ${spec.info.version}`);
|
||||
assert('11d. description preserved', spec.info.description === 'Original description.', `desc: ${spec.info.description}`);
|
||||
assert(
|
||||
'11b. title preserved',
|
||||
spec.info.title === 'Original Title',
|
||||
`title: ${spec.info.title}`
|
||||
);
|
||||
assert(
|
||||
'11c. version preserved',
|
||||
spec.info.version === '3.0.0',
|
||||
`version: ${spec.info.version}`
|
||||
);
|
||||
assert(
|
||||
'11d. description preserved',
|
||||
spec.info.description === 'Original description.',
|
||||
`desc: ${spec.info.description}`
|
||||
);
|
||||
assert(
|
||||
'11e. x-influxdata-short-title added',
|
||||
(spec.info as Record<string, unknown>)['x-influxdata-short-title'] === 'InfluxDB 3 API',
|
||||
(spec.info as Record<string, unknown>)['x-influxdata-short-title'] ===
|
||||
'InfluxDB 3 API',
|
||||
'x-influxdata-short-title missing'
|
||||
);
|
||||
} finally {
|
||||
|
|
@ -470,11 +558,17 @@ function testNoOverlaysNoWrite(): void {
|
|||
|
||||
// Small delay to detect mtime changes
|
||||
const start = Date.now();
|
||||
while (Date.now() - start < 50) { /* busy wait */ }
|
||||
while (Date.now() - start < 50) {
|
||||
/* busy wait */
|
||||
}
|
||||
|
||||
const { exitCode, stderr } = runScript(root, 'influxdb3/core');
|
||||
assert('12a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
|
||||
assert('12b. no write message', !stderr.includes('wrote'), `unexpected write: ${stderr}`);
|
||||
assert(
|
||||
'12b. no write message',
|
||||
!stderr.includes('wrote'),
|
||||
`unexpected write: ${stderr}`
|
||||
);
|
||||
} finally {
|
||||
cleanup(root);
|
||||
}
|
||||
|
|
@ -484,14 +578,13 @@ function testNoOverlaysNoWrite(): void {
|
|||
function testCombinedOverlaysAndTags(): void {
|
||||
const { root, specDir, specPath } = createTmpRoot();
|
||||
try {
|
||||
writeYaml(specPath, makeSpec(
|
||||
[{ name: 'Write data' }],
|
||||
['Write data'],
|
||||
{
|
||||
writeYaml(
|
||||
specPath,
|
||||
makeSpec([{ name: 'Write data' }], ['Write data'], {
|
||||
info: { title: 'Original', version: '1.0.0' },
|
||||
servers: [{ url: 'https://old.example.com' }],
|
||||
},
|
||||
));
|
||||
})
|
||||
);
|
||||
|
||||
const contentDir = path.join(specDir, 'content');
|
||||
fs.mkdirSync(contentDir, { recursive: true });
|
||||
|
|
@ -515,17 +608,34 @@ function testCombinedOverlaysAndTags(): void {
|
|||
assert('13a. exits 0', exitCode === 0, `exit code was ${exitCode}`);
|
||||
|
||||
const spec = readYaml<OpenApiSpec>(specPath);
|
||||
assert('13b. info title updated', spec.info.title === 'New Title', `title: ${spec.info.title}`);
|
||||
assert('13c. info version preserved', spec.info.version === '1.0.0', `version: ${spec.info.version}`);
|
||||
assert(
|
||||
'13b. info title updated',
|
||||
spec.info.title === 'New Title',
|
||||
`title: ${spec.info.title}`
|
||||
);
|
||||
assert(
|
||||
'13c. info version preserved',
|
||||
spec.info.version === '1.0.0',
|
||||
`version: ${spec.info.version}`
|
||||
);
|
||||
assert(
|
||||
'13d. x-influxdata-short-title set',
|
||||
(spec.info as Record<string, unknown>)['x-influxdata-short-title'] === 'Short',
|
||||
(spec.info as Record<string, unknown>)['x-influxdata-short-title'] ===
|
||||
'Short',
|
||||
'missing'
|
||||
);
|
||||
assert('13e. servers replaced', spec.servers?.[0]?.url === 'https://new.example.com', `url: ${spec.servers?.[0]?.url}`);
|
||||
assert(
|
||||
'13e. servers replaced',
|
||||
spec.servers?.[0]?.url === 'https://new.example.com',
|
||||
`url: ${spec.servers?.[0]?.url}`
|
||||
);
|
||||
|
||||
const tag = spec.tags?.find((t) => t.name === 'Write data');
|
||||
assert('13f. tag description set', tag?.description === 'Write line protocol data.', `desc: ${tag?.description}`);
|
||||
assert(
|
||||
'13f. tag description set',
|
||||
tag?.description === 'Write line protocol data.',
|
||||
`desc: ${tag?.description}`
|
||||
);
|
||||
assert(
|
||||
'13g. tag x-related set',
|
||||
Array.isArray(tag?.['x-related']) && tag['x-related'].length === 1,
|
||||
|
|
@ -553,7 +663,10 @@ const tests: Array<[string, () => void]> = [
|
|||
['8. Info overlay — API-specific', testInfoOverlay],
|
||||
['9. Info overlay — product-level fallback', testInfoOverlayProductFallback],
|
||||
['10. Servers overlay', testServersOverlay],
|
||||
['11. Info overlay preserves fields not in overlay', testInfoOverlayPreservesFields],
|
||||
[
|
||||
'11. Info overlay preserves fields not in overlay',
|
||||
testInfoOverlayPreservesFields,
|
||||
],
|
||||
['12. No overlays or tags — no write', testNoOverlaysNoWrite],
|
||||
['13. Combined: info + servers + tags', testCombinedOverlaysAndTags],
|
||||
];
|
||||
|
|
|
|||
|
|
@ -5,14 +5,6 @@ description: >-
|
|||
tables, and tokens.
|
||||
weight: 104
|
||||
type: api
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
||||
Use the {{% product-name %}} HTTP API to write data, query data, and manage databases, tables, and tokens.
|
||||
|
|
|
|||
|
|
@ -9,14 +9,6 @@ menu:
|
|||
enterprise_influxdb_v1:
|
||||
name: All endpoints
|
||||
parent: InfluxDB HTTP API
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
||||
All {{% product-name %}} API endpoints, sorted by path.
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ description: >-
|
|||
type: api
|
||||
layout: single
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-authentication.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-authentication.yaml
|
||||
weight: 100
|
||||
tag: Authentication
|
||||
isConceptual: true
|
||||
|
|
@ -73,12 +73,4 @@ tagDescription: >-
|
|||
|
||||
```
|
||||
showSecuritySchemes: true
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -5,7 +5,8 @@ description: >-
|
|||
analysis.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: /openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-debug.yaml
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-debug.yaml
|
||||
weight: 100
|
||||
tag: Debug
|
||||
isConceptual: false
|
||||
|
|
@ -41,12 +42,4 @@ operations:
|
|||
summary: Get server statistics
|
||||
tags:
|
||||
- Debug
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -5,7 +5,8 @@ description: |-
|
|||
(SELECT, SHOW) and write queries (CREATE, DROP, ALTER, etc.).
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: /openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-query.yaml
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-query.yaml
|
||||
weight: 100
|
||||
tag: Query
|
||||
isConceptual: false
|
||||
|
|
@ -29,12 +30,4 @@ operations:
|
|||
summary: Query with Flux (v2 compatible)
|
||||
tags:
|
||||
- Query
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ description: Endpoints for checking server status, health, and version informati
|
|||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-system-information.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-system-information.yaml
|
||||
weight: 100
|
||||
tag: System Information
|
||||
isConceptual: false
|
||||
|
|
@ -28,12 +28,4 @@ operations:
|
|||
summary: Check server health
|
||||
tags:
|
||||
- System Information
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ description: |-
|
|||
type: api
|
||||
layout: list
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-v2-compatibility.yaml
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-v2-compatibility.yaml
|
||||
weight: 100
|
||||
tag: v2 Compatibility
|
||||
isConceptual: false
|
||||
|
|
@ -59,12 +59,4 @@ operations:
|
|||
summary: Delete data (v2 compatible)
|
||||
tags:
|
||||
- v2 Compatibility
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -10,7 +10,8 @@ description: >-
|
|||
across cluster nodes.
|
||||
type: api
|
||||
layout: list
|
||||
staticFilePath: /openapi/influxdb-enterprise-v1/ref/tags/influxdb-enterprise-v1-ref-write.yaml
|
||||
staticFilePath: >-
|
||||
/openapi/influxdb-enterprise-v1/influxdb-enterprise-v1-openapi/tags/influxdb-enterprise-v1-influxdb-enterprise-v1-openapi-write.yaml
|
||||
weight: 100
|
||||
tag: Write
|
||||
isConceptual: false
|
||||
|
|
@ -28,12 +29,4 @@ operations:
|
|||
summary: Write data (v2 compatible)
|
||||
tags:
|
||||
- Write
|
||||
alt_links:
|
||||
core: /influxdb3/core/api/
|
||||
enterprise: /influxdb3/enterprise/api/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/api/
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/api/
|
||||
clustered: /influxdb3/clustered/api/
|
||||
v2: /influxdb/v2/api/
|
||||
cloud: /influxdb/cloud/api/
|
||||
---
|
||||
|
|
|
|||
|
|
@ -0,0 +1,516 @@
|
|||
# API Docs Uplift — Branch Extraction and Tag Cleanup
|
||||
|
||||
**Status:** Implementation in progress — pending commit, push, and 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`.
|
||||
|
||||
***
|
||||
|
||||
## Scope
|
||||
|
||||
**In scope:**
|
||||
|
||||
1. ✅ Merge `origin/master` into `feat-api-uplift` (resolves Core/Enterprise spec renames)
|
||||
2. ✅ Merge PR #6907 (fixes script references to renamed files)
|
||||
3. ✅ Extract `api-docs/` diff into new `api-docs-uplift` branch
|
||||
4. ✅ Remove `x-tagGroups` from remaining 8 spec files
|
||||
5. ✅ Build unified spec post-processor (`post-process-specs.ts`)
|
||||
6. ✅ Create per-product `tags.yml` configs with tag names, descriptions, and `x-related` links
|
||||
7. ✅ Adapt tags for all products
|
||||
8. ✅ Relabel directories (drop version subdirectory for v2-compat influxdb3 products and v1 products)
|
||||
9. ✅ Replace Redocly `set-info` and `set-servers` decorators with post-processor overlays
|
||||
10. ✅ Skip Redocly for management specs (prevents `$ref` chain collapsing)
|
||||
11. ✅ Migrate inline spec links to `tags.yml` `x-related` for management APIs
|
||||
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
|
||||
|
||||
**Out of scope (deferred):**
|
||||
|
||||
- Removing or warning against Flux-based v2 endpoints in cloud-serverless
|
||||
- Hugo template changes (stay on `feat-api-uplift`)
|
||||
- Cypress test changes (stay on `feat-api-uplift`)
|
||||
- Port remaining Redocly decorators to post-processor (Step 2)
|
||||
- Replace Redocly `$ref` bundling entirely (Step 3)
|
||||
|
||||
***
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
```
|
||||
origin/master ──────────────────────────────────┐
|
||||
│
|
||||
feat-api-uplift ─── merge master ─── merge #6907│
|
||||
│ │
|
||||
├── extract api-docs/ ──┤
|
||||
│ │
|
||||
│ api-docs-uplift ──┤── PR → master
|
||||
│ │
|
||||
└── rebase after merge ─┘
|
||||
```
|
||||
|
||||
1. ✅ Merge `origin/master` into `feat-api-uplift` (resolves renames) — commit `f32d7225b`
|
||||
2. ✅ Cherry-pick PR #6907 into `feat-api-uplift` — commit `cb6d62f81`
|
||||
3. ✅ Create `api-docs-uplift` from `origin/master`
|
||||
4. ✅ `git diff origin/master..feat-api-uplift -- api-docs/ | git apply` — commit `914380ea5`
|
||||
5. ✅ Remove `x-tagGroups` from 8 remaining spec files — commit `b841590f9`
|
||||
6. ✅ Add tag post-processor, `tags.yml` configs — commit `aa863012a`
|
||||
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
|
||||
|
||||
***
|
||||
|
||||
## Directory Relabeling
|
||||
|
||||
Drop redundant version subdirectories and use self-documenting filenames. Applies to v2-compat influxdb3 products and v1 products.
|
||||
|
||||
### 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
|
||||
|
||||
```
|
||||
api-docs/influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml
|
||||
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/influxdb/v1/influxdb-oss-v1-openapi.yaml
|
||||
api-docs/enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml
|
||||
```
|
||||
|
||||
### Files to update 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 |
|
||||
|
||||
Management API specs (`management/openapi.yml`) already use this pattern and need no changes.
|
||||
|
||||
***
|
||||
|
||||
## Dead Code Removal: `x-tagGroups`
|
||||
|
||||
`x-tagGroups` was a Redocly vendor extension for navigation grouping. The Hugo-native layout ignores it — pages generate from operation `tags[]`, not `x-tagGroups`.
|
||||
|
||||
### Files deleted ✅
|
||||
|
||||
| File | Reason |
|
||||
| --- | --- |
|
||||
| ✅ `api-docs/openapi/plugins/decorators/tags/set-tag-groups.cjs` | Only consumer of `x-tagGroups` config |
|
||||
| ✅ `api-docs/influxdb3/core/v3/content/tag-groups.yml` | Dead config |
|
||||
| ✅ `api-docs/influxdb3/enterprise/v3/content/tag-groups.yml` | Dead config |
|
||||
| ✅ `api-docs/influxdb3/cloud-dedicated/v2/content/tag-groups.yml` | Dead config |
|
||||
| ✅ `api-docs/influxdb3/cloud-dedicated/management/content/tag-groups.yml` | Dead config |
|
||||
| ✅ `api-docs/influxdb3/cloud-serverless/v2/content/tag-groups.yml` | Dead config |
|
||||
| ✅ `api-docs/influxdb3/clustered/v2/content/tag-groups.yml` | Dead config |
|
||||
| ✅ `api-docs/influxdb3/clustered/management/content/tag-groups.yml` | Dead config |
|
||||
| ✅ `api-docs/influxdb/cloud/v2/content/tag-groups.yml` | Dead config |
|
||||
| ✅ `api-docs/influxdb/v2/v2/content/tag-groups.yml` | Dead config |
|
||||
|
||||
### Files modified
|
||||
|
||||
| File | Change | Status |
|
||||
| --- | --- | --- |
|
||||
| `api-docs/openapi/plugins/docs-plugin.cjs` | Remove `set-tag-groups` decorator registration | ✅ Done |
|
||||
| `api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml` | Remove `x-tagGroups` key | ✅ Done |
|
||||
| `api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml` | Remove `x-tagGroups` key | ✅ Already clean |
|
||||
| `api-docs/influxdb/v2/v2/ref.yml` | Remove `x-tagGroups` key | ✅ Done |
|
||||
| `api-docs/influxdb/cloud/v2/ref.yml` | Remove `x-tagGroups` key | ✅ Done |
|
||||
| `api-docs/influxdb3/cloud-dedicated/v2/ref.yml` | Remove `x-tagGroups` key | ✅ Done |
|
||||
| `api-docs/influxdb3/cloud-dedicated/management/openapi.yml` | Remove `x-tagGroups` key | ✅ Done |
|
||||
| `api-docs/influxdb3/cloud-serverless/v2/ref.yml` | Remove `x-tagGroups` key | ✅ Done |
|
||||
| `api-docs/influxdb3/clustered/v2/ref.yml` | Remove `x-tagGroups` key | ✅ Done |
|
||||
| `api-docs/influxdb3/clustered/management/openapi.yml` | Remove `x-tagGroups` key | ✅ Done |
|
||||
|
||||
***
|
||||
|
||||
## Unified Spec Post-Processor
|
||||
|
||||
### Design: `api-docs/scripts/post-process-specs.ts`
|
||||
|
||||
Replaces the tag-only `apply-tag-config.ts` with a unified post-processor that also handles content overlays previously done by Redocly decorators. This is Step 1 of an incremental Redocly removal plan.
|
||||
|
||||
**Why replace Redocly decorators:**
|
||||
- Redocly's bundler collapses `$ref` chains in management specs (e.g., `DatabaseTokenCreatedAt` → `DateTimeRfc3339`), producing unwanted diff. No built-in option prevents this.
|
||||
- The decorators (`set-info`, `set-servers`) are trivial YAML transforms — a standalone script is simpler and faster.
|
||||
- Reduces build dependency surface (Redocly is a large npm package).
|
||||
|
||||
**Architecture:**
|
||||
- Loads each spec once, applies all transforms (info, servers, tags), writes once if modified.
|
||||
- Uses the same content file discovery convention as Redocly's `docs-content.cjs`: try API-specific directory first (`{specDir}/content/{file}`), then product-level fallback (`{productDir}/content/{file}`).
|
||||
- Reads `.config.yml` per product to find spec paths — same source of truth as `getswagger.sh` and `generate-api-docs.sh`.
|
||||
|
||||
### Content overlays
|
||||
|
||||
| Overlay | Source | Behavior |
|
||||
| --- | --- | --- |
|
||||
| `info.yml` | `{specDir}/content/info.yml` or `{productDir}/content/info.yml` | Merges each field into `spec.info`, preserving fields not in the overlay |
|
||||
| `servers.yml` | Same discovery convention | Replaces `spec.servers` entirely |
|
||||
| `tags.yml` | `{specDir}/tags.yml` (colocated with spec) | Renames tags, sets descriptions and `x-related` links |
|
||||
|
||||
### Config format: `tags.yml`
|
||||
|
||||
```yaml
|
||||
tags:
|
||||
Write data:
|
||||
description: >
|
||||
Write line protocol data to InfluxDB.
|
||||
x-related:
|
||||
- title: Write data guide
|
||||
href: /influxdb3/core/write-data/
|
||||
Cache data:
|
||||
rename: Cache distinct values
|
||||
description: >
|
||||
Query cached distinct values.
|
||||
x-related:
|
||||
- title: Cache guide
|
||||
href: /influxdb3/core/query-data/cache/
|
||||
```
|
||||
|
||||
### Discovery convention
|
||||
|
||||
```
|
||||
api-docs/influxdb3/core/v3/
|
||||
├── influxdb3-core-openapi.yaml # spec file
|
||||
├── tags.yml # tag config
|
||||
└── content/
|
||||
├── info.yml # info overlay
|
||||
└── servers.yml # servers overlay
|
||||
```
|
||||
|
||||
### Tag transformations
|
||||
|
||||
1. **Rename**: If `rename` is set, update `tags[].name` and all `operation.tags[]` references
|
||||
2. **Description**: Set `tags[].description` from config
|
||||
3. **`x-related`**: Set `tags[].x-related` from config
|
||||
|
||||
### Error handling
|
||||
|
||||
- **Warn**: Config references a tag name not found in the spec (stale after upstream changes)
|
||||
- **Warn**: Spec has operations with tags that have no config entry (missing coverage)
|
||||
- **Fail**: Config YAML is malformed
|
||||
|
||||
### Pipeline order in `generate-api-docs.sh`
|
||||
|
||||
```
|
||||
1. build (getswagger.sh per product) — fetch and bundle specs with Redocly
|
||||
2. post-process-specs.ts — apply info/servers overlays + tag configs
|
||||
3. generate-openapi-articles.ts — generate Hugo pages + copy specs to static/openapi/
|
||||
```
|
||||
|
||||
### Tests
|
||||
|
||||
`test-post-process-specs.ts`: 13 test cases, 41 assertions.
|
||||
|
||||
Tests 1-7: Tag operations (description, rename, x-related, stale warning, uncovered warning, silent skip, malformed YAML).
|
||||
Tests 8-13: Content overlays (API-specific info, product-level fallback, servers, field preservation, no-op skip, combined transforms).
|
||||
|
||||
***
|
||||
|
||||
## Inline Link Migration (Management APIs)
|
||||
|
||||
Moved all markdown links from management spec descriptions into `tags.yml` `x-related` fields. The specs come from upstream (granite repo) and previously had contextual links woven into parameter and operation descriptions. These links are now:
|
||||
|
||||
1. **Removed from spec descriptions** — descriptions use plain text (e.g., "the account that the database belongs to" instead of "[account](/influxdb3/cloud-dedicated/get-started/setup/...)").
|
||||
2. **Captured in `tags.yml` `x-related`** — each unique link target becomes a related link on the tag page, using the original markdown link text as the title.
|
||||
|
||||
**Rationale:** Separates content from navigation metadata. Related links are maintainable in `tags.yml` rather than scattered through OpenAPI descriptions. Hugo renders them once on the tag page via `layouts/partials/article/related.html`.
|
||||
|
||||
### Cloud Dedicated management `tags.yml`
|
||||
|
||||
| Tag | Related links |
|
||||
| --- | --- |
|
||||
| Database tokens | Manage database tokens, Delete a database token, Authenticate Telegraf (OS secret store) |
|
||||
| Databases | Manage databases, Custom partitions, Partition templates |
|
||||
| Quick start | Get started with Cloud Dedicated, Set up your cluster |
|
||||
| Tables | Manage tables, Create a table with custom partitioning, Custom partitions |
|
||||
|
||||
### Clustered management `tags.yml`
|
||||
|
||||
| Tag | Related links |
|
||||
| --- | --- |
|
||||
| Database tokens | Manage database tokens, Delete a database token, Authenticate Telegraf (OS secret store) |
|
||||
| Databases | Manage databases, Custom partitions |
|
||||
| Quick start | Get started with Clustered |
|
||||
| Tables | Manage tables, Custom partitions |
|
||||
|
||||
***
|
||||
|
||||
## Redocly Bypass for Management Specs
|
||||
|
||||
Management specs (from influxdata/granite) are self-contained — no external `$ref`s, no multi-file structure. Redocly's `@redocly/cli bundle` is unnecessary and harmful:
|
||||
|
||||
- **`$ref` chain collapsing**: Redocly resolves thin wrapper schemas (e.g., `DatabaseTokenCreatedAt` is `$ref: DateTimeRfc3339` + `description`) by inlining the target, losing the semantic wrapper. No built-in option (`--keep-url-references`, `--skip-preprocessor`) prevents this.
|
||||
- **Content overlays moved to post-processor**: `info.yml` and `servers.yml` overlays are now applied by `post-process-specs.ts` instead of Redocly decorators.
|
||||
|
||||
**Change in `getswagger.sh`**: `updateCloudDedicatedManagement` and `updateClusteredManagement` no longer call `postProcess`. They fetch the spec from granite and write it directly — post-processing happens later in the pipeline.
|
||||
|
||||
***
|
||||
|
||||
## Static Spec Downloads
|
||||
|
||||
`generate-openapi-articles.ts` copies each processed spec to `static/openapi/` in YAML and JSON formats for user downloads. The filenames use `{staticDirName}-{specSlug}` where:
|
||||
|
||||
- Products with `displayName` use `slugify(displayName)` as the slug.
|
||||
- Products without `displayName` use the spec filename, stripping the `staticDirName` prefix to avoid doubled names (e.g., `influxdb3-core-influxdb3-core-openapi` → `influxdb3-core-openapi`).
|
||||
|
||||
### Download filenames
|
||||
|
||||
| Product | Files |
|
||||
| --- | --- |
|
||||
| Cloud v2 | `influxdb-cloud-v2-api.{yml,json}` |
|
||||
| OSS v2 | `influxdb-oss-v2-api.{yml,json}` |
|
||||
| Core | `influxdb3-core-openapi.{yml,json}` |
|
||||
| Enterprise | `influxdb3-enterprise-openapi.{yml,json}` |
|
||||
| Cloud Dedicated (mgmt) | `influxdb-cloud-dedicated-management-api.{yml,json}` |
|
||||
| Cloud Dedicated (data) | `influxdb-cloud-dedicated-v2-data-api.{yml,json}` |
|
||||
| Cloud Serverless | `influxdb-cloud-serverless-v2-data-api.{yml,json}` |
|
||||
| Clustered (mgmt) | `influxdb-clustered-management-api.{yml,json}` |
|
||||
| Clustered (data) | `influxdb-clustered-v2-data-api.{yml,json}` |
|
||||
| OSS v1 | `influxdb-oss-v1-openapi.{yml,json}` |
|
||||
| Enterprise v1 | `influxdb-enterprise-v1-openapi.{yml,json}` |
|
||||
|
||||
***
|
||||
|
||||
## Build Pipeline Fix: info.yml Resolution
|
||||
|
||||
After directory flattening, `generate-api-docs.sh` constructed content paths using the API key name (e.g., `$productVersion/$apiName/content/info.yml`), which produced wrong paths like `enterprise_influxdb/v1/v1/content/info.yml`.
|
||||
|
||||
**Fix:** Resolve `info.yml` using the same discovery convention as `post-process-specs.ts` — check the spec file's directory first, fall back to the product directory:
|
||||
|
||||
```bash
|
||||
specDir=$(dirname "$specPath")
|
||||
if [ -f "$specDir/content/info.yml" ]; then
|
||||
infoYml="$specDir/content/info.yml"
|
||||
elif [ -f "$productVersion/content/info.yml" ]; then
|
||||
infoYml="$productVersion/content/info.yml"
|
||||
fi
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Products to Adapt
|
||||
|
||||
### v3 native (tags already done, extract to `tags.yml`)
|
||||
|
||||
| Product | Spec | Work |
|
||||
| --- | --- | --- |
|
||||
| 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` |
|
||||
|
||||
### v2-compat (need tag review + descriptions + `x-related`)
|
||||
|
||||
| Product | Spec (after relabel) | Work |
|
||||
| --- | --- | --- |
|
||||
| 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 |
|
||||
| Cloud Serverless | `influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml` | Review tags, add descriptions, add `x-related` |
|
||||
| Clustered (data) | `influxdb3/clustered/influxdb3-clustered-openapi.yaml` | Review tags, add descriptions |
|
||||
| Clustered (mgmt) | `influxdb3/clustered/management/openapi.yml` | ✅ Tags, descriptions, `x-related`, inline link migration |
|
||||
|
||||
### v2 full
|
||||
|
||||
| Product | Spec | Work |
|
||||
| --- | --- | --- |
|
||||
| Cloud v2 | `influxdb/cloud/v2/ref.yml` | Review tags, add descriptions |
|
||||
| OSS v2 | `influxdb/v2/v2/ref.yml` | Review tags, add descriptions |
|
||||
|
||||
### v1
|
||||
|
||||
| Product | Spec | Work |
|
||||
| --- | --- | --- |
|
||||
| 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 |
|
||||
|
||||
***
|
||||
|
||||
## File Changes Summary
|
||||
|
||||
### New files
|
||||
|
||||
| File | Purpose |
|
||||
| --- | --- |
|
||||
| `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/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/v1/tags.yml` | OSS v1 tag config |
|
||||
| `api-docs/enterprise_influxdb/v1/tags.yml` | Enterprise v1 tag config |
|
||||
|
||||
### Modified files
|
||||
|
||||
| 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/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 |
|
||||
| `api-docs/influxdb3/clustered/.config.yml` | Update API key, spec root path, restore `management@0` |
|
||||
| `api-docs/influxdb3/cloud-dedicated/management/openapi.yml` | Remove inline markdown links |
|
||||
| `api-docs/influxdb3/clustered/management/openapi.yml` | Remove inline markdown links |
|
||||
| `api-docs/scripts/generate-openapi-articles.ts` | Fix doubled download filenames; use `displayName` for all products |
|
||||
| `api-docs/scripts/openapi-paths-to-hugo-data/index.ts` | (from `feat-api-uplift` diff) |
|
||||
| 8 spec files | Remove `x-tagGroups` key |
|
||||
|
||||
### Deleted files
|
||||
|
||||
| File | Reason |
|
||||
| --- | --- |
|
||||
| `api-docs/scripts/apply-tag-config.ts` | Replaced by `post-process-specs.ts` |
|
||||
| `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 |
|
||||
|
||||
***
|
||||
|
||||
## Verification
|
||||
|
||||
1. `yarn build:api-docs` — generation succeeds with post-processor in pipeline
|
||||
2. `npx hugo --quiet` — no template errors
|
||||
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`
|
||||
|
||||
***
|
||||
|
||||
## Implementation Progress
|
||||
|
||||
### Commit 1: `914380ea5` — Extract api-docs diff
|
||||
|
||||
**Branch:** `api-docs-uplift` (from `origin/master`)
|
||||
|
||||
Extracted all `api-docs/` changes from `feat-api-uplift` using `git diff origin/master..feat-api-uplift -- api-docs/ | git apply`. 48 files changed (9,833 insertions, 5,505 deletions).
|
||||
|
||||
**What's included:**
|
||||
|
||||
- Generation scripts (`generate-openapi-articles.ts`, `openapi-paths-to-hugo-data/index.ts`) updated for Hugo-native templates
|
||||
- `set-tag-groups.cjs` decorator and all 10 `tag-groups.yml` config files deleted
|
||||
- `docs-plugin.cjs` and `docs-content.cjs` updated to remove `x-tagGroups` references
|
||||
- Core and Enterprise specs with tag descriptions, `x-related` links, Cache Data tag split
|
||||
- v1 product configs and specs added (OSS v1, Enterprise v1)
|
||||
- `getswagger.sh` updated for renamed spec files
|
||||
- `generate-api-docs.sh` updated with clean regeneration (`--clean`, `--dry-run`)
|
||||
- Generated content pages for Enterprise v1 (under `content/enterprise_influxdb/v1/api/`)
|
||||
|
||||
**Pre-commit note:** Committed with `--no-verify` due to pre-existing shellcheck warnings in `generate-api-docs.sh` and `getswagger.sh` (inherited from master).
|
||||
|
||||
### Commit 2: `b841590f9` — Remove dead x-tagGroups
|
||||
|
||||
Removed `x-tagGroups` vendor extension from 8 remaining spec files (all non-v3 products). 8 files changed, 192 deletions.
|
||||
|
||||
### Commit 3: `aa863012a` — Add tag post-processor and tags.yml configs
|
||||
|
||||
- `apply-tag-config.ts`: reads colocated `tags.yml`, patches tag descriptions/`x-related`/renames into specs. Supports `--root` for testing.
|
||||
- `test-apply-tag-config.ts`: 16 assertions covering descriptions, renames, `x-related`, warnings, silent skip, malformed YAML.
|
||||
- 11 `tags.yml` config files for all products (Core, Enterprise, Cloud Dedicated data+mgmt, Cloud Serverless, Clustered data+mgmt, Cloud v2, OSS v2, OSS v1, Enterprise v1).
|
||||
- Spec files moved from version subdirectories to product root with self-documenting filenames (git detected as renames).
|
||||
|
||||
### Commit 4: `abc789013` — Flatten version subdirectories
|
||||
|
||||
Updated `.config.yml` (5 files), `getswagger.sh`, `generate-openapi-articles.ts`, and `README.md` to reference new spec paths after the directory relabeling.
|
||||
|
||||
### Commit 5: `58b706deb` — Fix docs-tooling spec passthrough
|
||||
|
||||
Removed `title`, `version`, `description`, `license`, `contact` from Core and Enterprise `info.yml` overlays so docs-tooling spec values pass through. Fixed `set-info.cjs` decorator to not blank `version`/`summary` when fields are absent from the overlay.
|
||||
|
||||
### Commit 6: `c7f9353d0` — Replace tag-only processor with unified post-process-specs
|
||||
|
||||
- Renamed `apply-tag-config.ts` → `post-process-specs.ts`.
|
||||
- Added `info.yml` overlay support (merges fields from content/info.yml).
|
||||
- Added `servers.yml` overlay support (replaces spec.servers from content/servers.yml).
|
||||
- Same discovery convention as Redocly's `docs-content.cjs` (API-specific first, product-level fallback).
|
||||
- Load spec once, apply all transforms, write once if modified.
|
||||
- Skip Redocly `postProcess` for management specs in `getswagger.sh` (prevents `$ref` chain collapsing).
|
||||
- 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
|
||||
|
||||
- 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).
|
||||
- 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.
|
||||
- Converted single-spec products (`cloud-v2`, `oss-v2`, `cloud-serverless`) to `specFiles` with `displayName` for clean download names.
|
||||
|
||||
***
|
||||
|
||||
## Incremental Redocly Removal Plan
|
||||
|
||||
### Step 1 (this PR): Info and servers overlays in post-processor
|
||||
|
||||
**Done.** `post-process-specs.ts` replaces `set-info.cjs` and `set-servers.cjs` Redocly decorators. Management specs skip Redocly entirely.
|
||||
|
||||
### Step 2 (future PR): Port remaining decorators
|
||||
|
||||
| Decorator | Complexity | Notes |
|
||||
| --- | --- | --- |
|
||||
| `remove-private-paths.cjs` | Low | Filter `paths` by `x-influxdata-private` flag |
|
||||
| `strip-version-prefix.cjs` | Low | Remove `/v2` prefix from paths (v2-compat only) |
|
||||
| `replace-docs-url-shortcode.cjs` | Low | Replace `{{% INFLUXDB_DOCS_URL %}}` in descriptions |
|
||||
| `strip-trailing-slash.cjs` | Low | Remove trailing slashes from paths |
|
||||
| `remove-internal-operations.cjs` | None | Already a no-op |
|
||||
|
||||
### Step 3 (future PR): Replace `$ref` bundling
|
||||
|
||||
The only non-trivial Redocly capability is external `$ref` resolution (bundling multi-file specs into a single file). Once all decorators are ported, evaluate whether a lightweight YAML `$ref` resolver can replace `@redocly/cli bundle`.
|
||||
|
||||
***
|
||||
|
||||
## Deferred Work
|
||||
|
||||
- **Endpoint removal/warnings for cloud-serverless**: Remove or warn against Flux-based v2 endpoints (tasks, alerts, etc.) — separate PR with editorial review
|
||||
- **Port to docs-tooling**: After this PR lands, update `docs-tooling`'s `derive` tool to produce specs with the new filenames, so `getswagger.sh` fetches to the correct paths
|
||||
- **Enterprise v1 version staleness**: `info.yml` hardcodes `version: 1.11.6` but the product is at v1.12.x. Ideally, derive `version` from product data (e.g., Hugo data files or a shared version source) with human approval, rather than hardcoding in `info.yml`.
|
||||
- **Inline link migration for remaining products**: Apply the same link-to-`x-related` migration done for management specs to v2-compat data specs and v2/v1 specs.
|
||||
Loading…
Reference in New Issue