feat(api): InfluxDB3 Core API reference, API fixes, and e2e tests

- Adds InfluxDB 3 Core API reference
- Updates scripts
- Removes non-valid info.summary field from specs, replaces with description in metadata
- Simplifies frontmatter generation for HTML template
- Reorg of file structure to mirror the content structure.
- Moves OSS v2 into v2/v2/ref.yml to follow the same pattern as others
- Replaces isDefault API config field with specific aliases.
- Misc. fixes.
- Remove generated HTML files.
pull/5870/head
Jason Stirnaman 2025-02-21 17:22:56 -06:00
parent 846d3a9e46
commit b3bb9c40f1
39 changed files with 426 additions and 11353 deletions

2
.gitignore vendored
View File

@ -8,7 +8,7 @@ node_modules
*.log
/resources
.hugo_build.lock
/content/influxdb*/*/api/**/*.html
/content/influxdb*/**/api/**/*.html
/api-docs/redoc-static.html*
.vscode/*
.idea

View File

@ -41,7 +41,6 @@ function generateHtml {
local productName="$3"
local api="$4"
local configPath="$5"
local isDefault=$6
# Use the product name to define the menu for the Hugo template
local menu="$(echo $productVersion | sed 's/\./_/g;s/-/_/g;s/\//_/g;')"
@ -55,12 +54,25 @@ function generateHtml {
# 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 description=$(yq '.summary' $productVersion/$apiName/content/info.yml)
# Get the first paragraph of the description for the meta description.
# Get the description with whitespace and newlines preserved.
local description=$(yq e -r '.description // ""' $productVersion/$apiName/content/info.yml | sed ':a;N;$!ba;s/\n/\\n/g' | sed 's/"/\\"/g')
# 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.
if [[ "$aliases" == "null" ]]; then
aliases='[]'
fi
local weight=102
if [[ $apiName == "v1-compatibility" ]]; then
weight=304
fi
# Define the file name for the Redoc HTML output.
local specbundle=redoc-static_index.html
# Define the temporary file for the Hugo template and Redoc HTML.
local tmpfile="${productVersion}-${api}_index.tmp"
echo "Bundling $specPath"
# Use npx to install and run the specified version of redoc-cli.
@ -77,68 +89,24 @@ function generateHtml {
--options.hideHostname \
--options.noAutoAuth \
--output=$specbundle \
--templateOptions.description=$description \
--templateOptions.description= $(echo "$description" | sed 's/\n//g') \
--templateOptions.product="$productVersion" \
--templateOptions.productName="$productName"
if [[ $apiName == "v1-compatibility" ]]; then
frontmatter="---
title: $title
description: $description
layout: api
menu:
$menu:
parent: InfluxDB HTTP API
name: $menuTitle
identifier: api-reference-$apiName
weight: 304
aliases:
- /influxdb/$versionDir/api/v1/
local frontmatter=$(yq eval -n \
".title = \"$title\" |
.description = \"$description\" |
.layout = \"api\" |
.weight = $weight |
.menu.[\"$menu\"].parent = \"InfluxDB HTTP API\" |
.menu.[\"$menu\"].name = \"$menuTitle\" |
.menu.[\"$menu\"].identifier = \"api-reference-$apiName\" |
.aliases = \"$aliases\"")
frontmatter="---
$frontmatter
---
"
elif [[ $apiVersion == "0" ]]; then
echo $productName $apiName
frontmatter="---
title: $title
description: $description
layout: api
weight: 102
menu:
$menu:
parent: InfluxDB HTTP API
name: $menuTitle
identifier: api-reference-$apiName
---
"
elif [[ $isDefault == true ]]; then
frontmatter="---
title: $title
description: $description
layout: api
menu:
$menu:
parent: InfluxDB HTTP API
name: $menuTitle
identifier: api-reference-$apiName
weight: 102
aliases:
- /influxdb/$versionDir/api/
---
"
else
frontmatter="---
title: $title
description: $description
layout: api
menu:
$menu:
parent: InfluxDB HTTP API
name: $menuTitle
identifier: api-reference-$apiName
weight: 102
---
"
fi
# Create the Hugo template file with the frontmatter and Redoc HTML
echo "$frontmatter" >> $tmpfile
@ -199,13 +167,7 @@ function build {
if [ -d "$specPath" ] || [ ! -f "$specPath" ]; then
echo "OpenAPI spec $specPath doesn't exist."
fi
# Get default status from the configuration.
local isDefault=false
local defaultStatus
defaultStatus=$(yq e ".apis | .$api | .x-influxdata-default" "$configPath")
if [[ $defaultStatus == "true" ]]; then
isDefault=true
fi
# If the spec file differs from master, regenerate the HTML.
local update=0
@ -219,9 +181,9 @@ function build {
if [[ $update -eq 0 ]]; then
echo "Regenerating $version $api"
generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath" "$isDefault"
generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath"
fi
echo "========Done with $version $api========"
echo -e "========Finished $version $api========\n\n"
done <<< "$apis"
done
}

View File

@ -223,14 +223,14 @@ function updateEnterpriseV3 {
}
function updateOSSV2 {
outFile="influxdb/v2/ref.yml"
outFile="influxdb/v2/v2/ref.yml"
if [[ -z "$baseUrlOSS" ]];
then
echo "Using existing $outFile"
else
curl $UPDATE_OPTIONS ${baseUrlOSS}/contracts/ref/oss.yml -o $outFile
fi
postProcess $outFile 'influxdb/v2/.config.yml' '@2'
postProcess $outFile 'influxdb/v2/.config.yml' 'v2@2'
}
function updateV1Compat {

View File

@ -8,6 +8,9 @@ x-influxdata-product-name: InfluxDB v2 Cloud
apis:
v2@2:
root: v2/ref.yml
x-influxdata-default: true
x-influxdata-docs-aliases:
- /influxdb/cloud/api/
v1-compatibility@2:
root: v1-compatibility/swaggerV1Compat.yml
x-influxdata-docs-aliases:
- /influxdb/cloud/api/v1/

View File

@ -12212,7 +12212,7 @@ paths:
type: string
- description: |
A unix timestamp precision.
Formats timestamps as [unix (epoch) timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) the specified precision
Formats timestamps as [unix (epoch) timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) with the specified precision
instead of [RFC3339 timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
in: query
name: epoch

View File

@ -6,8 +6,11 @@ extends:
x-influxdata-product-name: InfluxDB v2 OSS
apis:
'@2':
root: ref.yml
x-influxdata-default: true
v2@2:
root: v2/ref.yml
x-influxdata-docs-aliases:
- /influxdb/v2/api/
v1-compatibility@2:
root: v1-compatibility/swaggerV1Compat.yml
x-influxdata-docs-aliases:
- /influxdb/v2/api/v1/

View File

@ -1,16 +0,0 @@
title: InfluxDB OSS API Service
x-influxdata-short-title: v2 API
summary: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
description: |
The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints.
This documentation is generated from the
[InfluxDB OpenAPI specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.7.0/contracts/ref/oss.yml).
version: 2.x
license:
name: MIT
url: 'https://opensource.org/licenses/MIT'
contact:
name: InfluxData
url: https://www.influxdata.com
email: support@influxdata.com

View File

@ -467,19 +467,3 @@ components:
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
x-tagGroups:
- name: Using the InfluxDB HTTP API
tags:
- Quick start
- Authentication
- Supported operations
- Headers
- Pagination
- Response codes
- Data I/O endpoints
- Security and access endpoints
- System information endpoints
- name: All endpoints
tags:
- Query
- Write

View File

@ -0,0 +1,17 @@
title: InfluxDB OSS API Service
x-influxdata-short-title: v2 API
description: |
The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints.
This documentation is generated from the
[InfluxDB OpenAPI specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.7.0/contracts/ref/oss.yml).
version: 2.x
license:
name: MIT
url: 'https://opensource.org/licenses/MIT'
contact:
name: InfluxData
url: https://www.influxdata.com
email: support@influxdata.com

View File

@ -3,6 +3,8 @@ info:
title: InfluxDB OSS API Service
version: 2.x
description: |
The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints.
This documentation is generated from the
@ -10,7 +12,10 @@ info:
license:
name: MIT
url: https://opensource.org/licenses/MIT
summary: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
contact:
name: InfluxData
url: https://www.influxdata.com
email: support@influxdata.com
servers:
- url: /
security:
@ -13103,7 +13108,7 @@ paths:
type: string
- description: |
A unix timestamp precision.
Formats timestamps as [unix (epoch) timestamps](/influxdb/v2.7/reference/glossary/#unix-timestamp) the specified precision
Formats timestamps as [unix (epoch) timestamps](/influxdb/v2.7/reference/glossary/#unix-timestamp) with the specified precision
instead of [RFC3339 timestamps](/influxdb/v2.7/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
in: query
name: epoch
@ -15515,9 +15520,9 @@ components:
properties:
results:
description: |
A resultset object that contains the `statement_id` and the `series` array.
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`.
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:
@ -15566,12 +15571,12 @@ components:
type: integer
type: object
oneOf:
- required:
- statement_id
- error
- required:
- statement_id
- series
- required:
- statement_id
- error
- required:
- statement_id
- series
type: array
type: object
IntegerLiteral:

View File

@ -10,6 +10,9 @@ apis:
root: management/openapi.yml
v2@2:
root: v2/ref.yml
x-influxdata-default: true
x-influxdata-docs-aliases:
- /influxdb3/cloud-dedicated/api/
v1-compatibility@2:
root: v1-compatibility/swaggerV1Compat.yml
x-influxdata-docs-aliases:
- /influxdb3/cloud-dedicated/api/v1/

View File

@ -2,6 +2,7 @@ title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Dedicated
x-influxdata-short-title: v1 Compatibility API
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

View File

@ -4,6 +4,7 @@ info:
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

View File

@ -2,9 +2,9 @@ openapi: 3.0.0
info:
title: InfluxDB v2 HTTP API for InfluxDB 3 Cloud Dedicated
description: |
The InfluxDB v2 HTTP API provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Cloud Dedicated database.
The InfluxDB v2 HTTP API provides a v2-compatible programmatic interface for writing and managing data stored in an InfluxDB 3 Cloud Dedicated database.
The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
Use the InfluxDB v2 HTTP API `/api/v2` endpoints to manage retention policy mappings and write data to an InfluxDB 3 instance.
This documentation is generated from the
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml).
@ -504,7 +504,7 @@ paths:
type: string
- description: |
A unix timestamp precision.
Formats timestamps as [unix (epoch) timestamps](/influxdb3/cloud-dedicated/reference/glossary/#unix-timestamp) the specified precision
Formats timestamps as [unix (epoch) timestamps](/influxdb3/cloud-dedicated/reference/glossary/#unix-timestamp) with the specified precision
instead of [RFC3339 timestamps](/influxdb3/cloud-dedicated/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
in: query
name: epoch

View File

@ -8,6 +8,9 @@ x-influxdata-product-name: InfluxDB 3 Serverless
apis:
v2@2:
root: v2/ref.yml
x-influxdata-default: true
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/

View File

@ -1,7 +1,8 @@
title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Serverless
x-influxdata-short-title: v1 Compatibility API
summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 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

View File

@ -3,6 +3,8 @@ 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
@ -14,7 +16,6 @@ info:
license:
name: MIT
url: https://opensource.org/licenses/MIT
summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket.
contact:
name: InfluxData
url: https://www.influxdata.com

View File

@ -1,8 +1,8 @@
title: InfluxDB 3 Cloud Serverless API Service
x-influxdata-short-title: v2 API
summary: |
The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
description: |
The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
This documentation is generated from the

View File

@ -2,6 +2,8 @@ openapi: 3.0.0
info:
title: InfluxDB 3 Cloud Serverless API Service
description: |
The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
This documentation is generated from the
@ -9,8 +11,6 @@ info:
license:
name: MIT
url: https://opensource.org/licenses/MIT
summary: |
The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
version: ''
contact:
name: InfluxData
@ -7827,7 +7827,7 @@ paths:
type: string
- description: |
A unix timestamp precision.
Formats timestamps as [unix (epoch) timestamps](/influxdb3/cloud-serverless/reference/glossary/#unix-timestamp) the specified precision
Formats timestamps as [unix (epoch) timestamps](/influxdb3/cloud-serverless/reference/glossary/#unix-timestamp) with the specified precision
instead of [RFC3339 timestamps](/influxdb3/cloud-serverless/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
in: query
name: epoch

View File

@ -8,6 +8,9 @@ x-influxdata-product-name: InfluxDB 3 Clustered
apis:
v2@2:
root: v2/ref.yml
x-influxdata-default: true
x-influxdata-docs-aliases:
- /influxdb3/clustered/api/
v1-compatibility@2:
root: v1-compatibility/swaggerV1Compat.yml
x-influxdata-docs-aliases:
- /influxdb3/clustered/api/v1/

View File

@ -1,7 +1,8 @@
title: InfluxDB v1 HTTP API for InfluxDB 3 Clustered
x-influxdata-short-title: v1 Compatibility API
summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 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

View File

@ -3,6 +3,8 @@ 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
@ -14,7 +16,6 @@ info:
license:
name: MIT
url: https://opensource.org/licenses/MIT
summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
contact:
name: InfluxData
url: https://www.influxdata.com

View File

@ -1,7 +1,8 @@
title: InfluxDB 3 Clustered API Service
x-influxdata-short-title: v2 API
summary: The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
description: |
The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
This documentation is generated from the

View File

@ -3,6 +3,8 @@ info:
title: InfluxDB 3 Clustered API Service
version: ''
description: |
The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
This documentation is generated from the
@ -10,7 +12,6 @@ info:
license:
name: MIT
url: https://opensource.org/licenses/MIT
summary: The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
contact:
name: InfluxData
url: https://www.influxdata.com
@ -521,7 +522,7 @@ paths:
type: string
- description: |
A unix timestamp precision.
Formats timestamps as [unix (epoch) timestamps](/influxdb3/clustered/reference/glossary/#unix-timestamp) the specified precision
Formats timestamps as [unix (epoch) timestamps](/influxdb3/clustered/reference/glossary/#unix-timestamp) with the specified precision
instead of [RFC3339 timestamps](/influxdb3/clustered/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
in: query
name: epoch

View File

@ -4,8 +4,9 @@ x-influxdata-version-matrix:
v1: Compatibility layer for InfluxDB 1.x clients (supported)
v2: Compatibility layer for InfluxDB 2.x clients (supported)
v3: Native API for InfluxDB 3.x (current)
summary: The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
description: |
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
Write and query data, and perform administrative tasks, such as managing databases and processing engine plugins.
The InfluxDB HTTP API for InfluxDB 3 Core includes endpoints for the following:

View File

@ -1,35 +1,58 @@
openapi: 3.0.3
info:
title: InfluxDB 3 Core HTTP API
description: HTTP API service for managing, writing to, and querying from InfluxDB 3 Core.
version: 1.0.2
title: InfluxDB 3 Core API Service
description: |
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
Write and query data, and perform administrative tasks, such as managing databases and processing engine plugins.
The InfluxDB HTTP API for InfluxDB 3 Core includes endpoints for the following:
- InfluxDB v1: Compatibility layer for InfluxDB 1.x clients (supported)
- `/api/v2`: Compatibility layer for InfluxDB 2.x clients (supported)
- `/api/v3`: Native API for InfluxDB 3.x (current)
<!-- TODO: verify where to host the spec that users can download.
This documentation is generated from the
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/).
-->
version: ''
license:
name: MIT
url: 'https://opensource.org/licenses/MIT'
url: https://opensource.org/licenses/MIT
contact:
name: InfluxData
url: https://www.influxdata.com
email: support@influxdata.com
servers:
- url: http://localhost:8080
description: Local development server
- url: https://{baseurl}
description: InfluxDB 3 Core API URL
variables:
baseurl:
enum:
- localhost:8181
default: localhost:8181
description: InfluxDB 3 Core URL
security:
- BearerAuth: []
tags:
- name: Databases
description: Create, read, update, and delete database and cache resources
- name: Tables
description: Manage table schemas and data
- name: Data operations
description: Write, query, and process data
- name: Backward compatibility
description: Endpoints compatible with v1.x and v2.x clients
- name: Data operations (write and query)
description: Write, query, and process data
- name: Databases
description: Create, read, update, and delete database and cache resources
- name: Processing engine
description: Manage processing engine triggers and plugins
- name: Server information
description: Retrieve server metrics, status, and version information
- name: Tables
description: Manage table schemas and data
paths:
/write:
post:
operationId: PostV1Write
summary: Write line protocol (v1-compatible)
description: >
description: |
Writes line protocol to the specified database.
This endpoint provides backward compatibility for InfluxDB 1.x write workloads using tools such as InfluxDB 1.x client libraries, the Telegraf `outputs.influxdb` output plugin, or third-party tools.
@ -38,19 +61,34 @@ paths:
Use query parameters to specify options for writing data.
parameters:
- $ref: '#/components/parameters/dbWriteParam'
- name: precision
in: query
required: true
- $ref: '#/components/parameters/compatibilityPrecisionParam'
- name: Content-Type
in: header
description: |
The content type of the request payload.
schema:
$ref: '#/components/schemas/PrecisionWrite'
description: Precision of timestamps.
- $ref: '#/components/parameters/ContentTypeLineProtocol'
$ref: '#/components/schemas/LineProtocol'
required: false
- name: Accept
in: header
description: |
The content type that the client can understand.
Writes only return a response body if they fail (partially or completely)--for example,
due to a syntax problem or type mismatch.
schema:
type: string
default: application/json
enum:
- application/json
required: false
- $ref: "#/components/parameters/ContentEncoding"
- $ref: "#/components/parameters/ContentLength"
requestBody:
$ref: '#/components/requestBodies/lineProtocolRequestBody'
responses:
"204":
description: Success ("No Content"). All data in the batch is written and queryable.
"400":
'400':
description: |
Bad request. Some (a _partial write_) or all of the data from the batch was rejected and not written.
If a partial write occurred, then some points from the batch are written and queryable.
@ -93,8 +131,6 @@ paths:
description: Access denied.
"413":
description: Request entity too large.
security:
- BearerAuth: []
tags:
- Backward compatibility
- Data operations
@ -102,7 +138,7 @@ paths:
post:
operationId: PostV2Write
summary: Write line protocol (v2-compatible)
description: >
description: |
Writes line protocol to the specified database.
This endpoint provides backward compatibility for InfluxDB 2.x write workloads using tools such as InfluxDB 2.x client libraries, the Telegraf `outputs.influxdb_v2` output plugin, or third-party tools.
@ -111,6 +147,13 @@ paths:
Use query parameters to specify options for writing data.
parameters:
- name: Content-Type
in: header
description: |
The content type of the request payload.
schema:
$ref: '#/components/schemas/LineProtocol'
required: false
- description: |
The compression applied to the line protocol in the request payload.
To send a gzip payload, pass `Content-Encoding: gzip` header.
@ -125,7 +168,6 @@ paths:
- gzip
- identity
type: string
- $ref: "#/components/parameters/ContentTypeLineProtocol"
- description: |
The size of the entity-body, in bytes, sent to InfluxDB.
in: header
@ -159,13 +201,7 @@ paths:
required: false
schema:
$ref: '#/components/schemas/AcceptPartial'
- name: precision
in: query
required: true
schema:
$ref: '#/components/schemas/PrecisionWrite'
description: The precision for unix timestamps in the line protocol batch.
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/compatibilityPrecisionParam'
requestBody:
$ref: '#/components/requestBodies/lineProtocolRequestBody'
responses:
@ -179,8 +215,6 @@ paths:
description: Access denied.
"413":
description: Request entity too large.
security:
- BearerAuth: []
tags:
- Backward compatibility
- Data operations
@ -188,7 +222,7 @@ paths:
post:
operationId: PostWriteLP
summary: Write line protocol
description: >
description: |
Writes line protocol to the specified database.
Use this endpoint to send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB.
@ -206,7 +240,27 @@ paths:
in: query
schema:
$ref: '#/components/schemas/NoSync'
- $ref: '#/components/parameters/ContentTypeLineProtocol'
- name: Content-Type
in: header
description: |
The content type of the request payload.
schema:
$ref: '#/components/schemas/LineProtocol'
required: false
- name: Accept
in: header
description: |
The content type that the client can understand.
Writes only return a response body if they fail (partially or completely)--for example,
due to a syntax problem or type mismatch.
schema:
type: string
default: application/json
enum:
- application/json
required: false
- $ref: "#/components/parameters/ContentEncoding"
- $ref: "#/components/parameters/ContentLength"
requestBody:
$ref: '#/components/requestBodies/lineProtocolRequestBody'
responses:
@ -222,8 +276,6 @@ paths:
description: Request entity too large.
"422":
description: Unprocessable entity.
security:
- BearerAuth: []
tags:
- Data operations
/api/v3/query_sql:
@ -279,8 +331,6 @@ paths:
description: Method not allowed.
"422":
description: Unprocessable entity.
security:
- BearerAuth: []
tags:
- Data operations
post:
@ -320,8 +370,6 @@ paths:
description: Method not allowed.
"422":
description: Unprocessable entity.
security:
- BearerAuth: []
tags:
- Data operations
/api/v3/query_influxql:
@ -370,8 +418,6 @@ paths:
description: Method not allowed.
"422":
description: Unprocessable entity.
security:
- BearerAuth: []
tags:
- Data operations
post:
@ -411,8 +457,6 @@ paths:
description: Method not allowed.
"422":
description: Unprocessable entity.
security:
- BearerAuth: []
tags:
- Data operations
/query:
@ -463,14 +507,6 @@ paths:
schema:
type: string
format: InfluxQL
- in: query
name: epoch
description: |
Map timestamps to UNIX epoch time, with the given precision.
The default is `ns`.
schema:
type: string
enum: [h, m, s, ms, u, ns]
- in: query
name: pretty
description: |
@ -484,6 +520,13 @@ paths:
required: true
schema:
type: string
- name: epoch
description: |
Formats timestamps as [unix (epoch) timestamps](/influxdb3/core/reference/glossary/#unix-timestamp) with the specified precision
instead of [RFC3339 timestamps](/influxdb3/core/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
in: query
schema:
$ref: '#/components/schemas/EpochCompatibility'
responses:
"200":
description: |
@ -521,8 +564,6 @@ paths:
description: Method not allowed.
"422":
description: Unprocessable entity.
security:
- BearerAuth: []
tags:
- Data operations
- Backward compatibility
@ -555,10 +596,26 @@ paths:
default: 10000
epoch:
description: |
Map timestamps to UNIX epoch time, with the given precision.
The default is `ns`.
A unix timestamp precision.
- `h` for hours
- `m` for minutes
- `s` for seconds
- `ms` for milliseconds
- `u` or `µ` for microseconds
- `ns` for nanoseconds
Formats timestamps as [unix (epoch) timestamps](/influxdb3/core/reference/glossary/#unix-timestamp) with the specified precision
instead of [RFC3339 timestamps](/influxdb3/core/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
enum:
- ns
- u
- µ
- ms
- s
- m
- h
type: string
enum: [h, m, s, ms, u, ns]
pretty:
description: |
If true, the JSON response is formatted in a human-readable format.
@ -619,8 +676,6 @@ paths:
description: Method not allowed.
"422":
description: Unprocessable entity.
security:
- BearerAuth: []
tags:
- Data operations
- Backward compatibility
@ -696,8 +751,6 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Database not found.
security:
- BearerAuth: []
tags:
- Databases
post:
@ -719,8 +772,6 @@ paths:
$ref: '#/components/responses/Unauthorized'
"409":
description: Database already exists.
security:
- BearerAuth: []
tags:
- Databases
delete:
@ -738,8 +789,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Database not found.
security:
- BearerAuth: []
tags:
- Databases
/api/v3/configure/table:
@ -763,8 +813,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Database not found.
security:
- BearerAuth: []
tags:
- Tables
delete:
@ -787,8 +836,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Table not found.
security:
- BearerAuth: []
tags:
- Tables
/api/v3/configure/distinct_cache:
@ -796,6 +844,8 @@ paths:
operationId: PostConfigureDistinctCache
summary: Create distinct cache
description: Creates a distinct cache for a table.
tags:
- Tables
requestBody:
required: true
content:
@ -834,8 +884,7 @@ paths:
description: Cache not found.
"409":
description: Cache already exists.
security:
- BearerAuth: []
tags:
- Tables
delete:
@ -863,8 +912,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Cache not found.
security:
- BearerAuth: []
tags:
- Tables
/api/v3/configure/processing_engine_trigger:
@ -887,10 +935,9 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Trigger not found.
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
delete:
operationId: DeleteConfigureProcessingEngineTrigger
summary: Delete processing engine trigger
@ -917,10 +964,9 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Trigger not found.
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
/api/v3/configure/processing_engine_trigger/disable:
post:
operationId: PostDisableProcessingEngineTrigger
@ -943,10 +989,9 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Trigger not found.
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
/api/v3/configure/processing_engine_trigger/enable:
post:
operationId: PostEnableProcessingEngineTrigger
@ -969,10 +1014,9 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Trigger not found.
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
/api/v3/configure/plugin_environment/install_packages:
post:
operationId: PostInstallPluginPackages
@ -994,10 +1038,8 @@ paths:
description: Bad request.
"401":
$ref: '#/components/responses/Unauthorized'
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
/api/v3/configure/plugin_environment/install_requirements:
post:
operationId: PostInstallPluginRequirements
@ -1019,10 +1061,8 @@ paths:
description: Bad request.
"401":
$ref: '#/components/responses/Unauthorized'
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
/api/v3/plugin_test/wal:
post:
operationId: PostTestWALPlugin
@ -1037,10 +1077,8 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Plugin not enabled.
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
/api/v3/plugin_test/schedule:
post:
operationId: PostTestSchedulingPlugin
@ -1055,10 +1093,8 @@ paths:
$ref: '#/components/responses/Unauthorized'
"404":
description: Plugin not enabled.
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
/api/v3/engine/{plugin_path}:
parameters:
- name: plugin_path
@ -1105,10 +1141,8 @@ paths:
description: Plugin not found.
"500":
description: Processing failure.
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
post:
operationId: PostProcessingEnginePluginRequest
summary: On-request processing engine plugin request
@ -1133,10 +1167,9 @@ paths:
description: Plugin not found.
"500":
description: Processing failure.
security:
- BearerAuth: []
tags:
- Data operations
- Processing engine
components:
parameters:
AcceptQueryHeader:
@ -1168,25 +1201,17 @@ components:
description: |
The size of the entity-body, in bytes, sent to InfluxDB.
schema:
$ref: '#/components/schemas/ContentLength'
$ref: '#/components/schemas/ContentLength'
ContentType:
name: Content-Type
description: |
The format of the data in the request body.
in: header
schema:
type: string
enum:
- application/json
required: false
ContentTypeLineProtocol:
name: Content-Type
in: header
description: |
The format of the data in the request body.
To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`.
schema:
$ref: '#/components/schemas/LineProtocol'
required: false
db:
name: db
in: query
@ -1202,6 +1227,7 @@ components:
schema:
type: string
description: |
The name of the database.
The name of the database.
InfluxDB creates the database if it doesn't already exist, and then
writes all points in the batch to the database.
@ -1256,6 +1282,7 @@ components:
required: true
schema:
$ref: '#/components/schemas/Format'
requestBodies:
lineProtocolRequestBody:
required: true
@ -1266,7 +1293,7 @@ components:
examples:
line:
summary: Example line protocol
value: "measurement,tag=value field=1 1234567890"
value: measurement,tag=value field=1 1234567890
multiline:
summary: Example line protocol with UTF-8 characters
value: |
@ -1282,14 +1309,18 @@ components:
schemas:
ContentEncoding:
type: string
enum: [gzip, identity]
enum:
- gzip
- identity
description: |
Content coding.
Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.
default: identity
LineProtocol:
type: string
enum: [text/plain, text/plain; charset=utf-8]
enum:
- text/plain
- text/plain; charset=utf-8
description: |
`text/plain` is the content type for line protocol. `UTF-8` is the default character set.
default: text/plain; charset=utf-8
@ -1361,9 +1392,9 @@ components:
- database
- query_str
example:
database: "mydb"
query_str: "SELECT * FROM mytable"
format: "json"
database: mydb
query_str: SELECT * FROM mytable
format: json
params: {}
CreateDatabaseRequest:
type: object
@ -1398,7 +1429,6 @@ components:
required:
- db
- table
- fields
- tags
DistinctCacheCreateRequest:
type: object
@ -1425,9 +1455,11 @@ components:
- table
- columns
example:
db: "mydb"
table: "mytable"
columns: ["tag1", "tag2"]
db: mydb
table: mytable
columns:
- tag1
- tag2
max_cardinality: 1000
max_age: 3600
LastCacheCreateRequest:
@ -1460,10 +1492,12 @@ components:
- db
- table
example:
db: "mydb"
table: "mytable"
key_columns: ["tag1"]
value_columns: ["field1"]
db: mydb
table: mytable
key_columns:
- tag1
value_columns:
- field1
count: 100
ttl: 3600
ProcessingEngineTriggerRequest:
@ -1504,9 +1538,13 @@ components:
example:
results:
- series:
- name: "mytable"
columns: ["time", "value"]
values: [["2024-02-02T12:00:00Z", 42]]
- name: mytable
columns:
- time
- value
values:
- - '2024-02-02T12:00:00Z'
- 42
ErrorMessage:
type: object
properties:
@ -1547,6 +1585,24 @@ components:
type: string
required:
- code
EpochCompatibility:
description: |
A unix timestamp precision.
- `h` for hours
- `m` for minutes
- `s` for seconds
- `ms` for milliseconds
- `u` or `µ` for microseconds
- `ns` for nanoseconds
enum:
- ns
- u
- µ
- ms
- s
- m
- h
type: string
responses:
# // Source https://github.com/influxdata/influxdb/blob/main/influxdb3_server/src/http.rs
Unauthorized:
@ -1555,7 +1611,7 @@ components:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
Bad request:
BadRequest:
description: |
Request failed. Possible reasons:

View File

@ -4,8 +4,9 @@ x-influxdata-version-matrix:
v1: Compatibility layer for InfluxDB 1.x clients (supported)
v2: Compatibility layer for InfluxDB 2.x clients (supported)
v3: Native API for InfluxDB 3.x (current)
summary: The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
description: |
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
Write and query data, and perform administrative tasks, such as managing databases and processing engine plugins.
The InfluxDB HTTP API for InfluxDB 3 Core includes endpoints for the following:

File diff suppressed because it is too large Load Diff

View File

@ -12,7 +12,7 @@
<meta charset="utf8" />
<title>{{title}}</title>
<meta name="description" content="{{templateOptions.description}}.">
<meta name="description" content="{{templateOptions.description}}">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="shortcut icon" href="/img/favicon.png" type="image/png" sizes="32x32">

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

View File

@ -32,8 +32,8 @@ describe('API reference content', () => {
'/influxdb3/clustered/api/v1/',
'/influxdb3/clustered/api/v1-compatibility/',
'/influxdb3/clustered/api/v2/',
'/influxdb3/core/api/',
'/influxdb3/core/api/',
'/influxdb3/enterprise/api/',
];