Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fix/api securityschemes (#3488) 

* fix: oss and cloud auth. Add bearer scheme for OSS.

* chore: Add an openapi CLI decorator that replaces INFLUXDB_DOCS_URL 'shortcodes' with the correct URL in specs.

* fix: API authentication descriptions and schemes in /api/v2 and V1Compat. Remove QueryString and Basic auth schemes from /api/v2 and add them to V1Compat, along with Token auth. Hook up the replace-docs-url-shortcode which is primarily for V1Compat for now due to the way that contract is managed. Add tag groups to V1Compat.

* fix: add v1compat Info description. Comment out Bearer auth in OSS until it's available in Cloud.

* fix: add replace-shortcodes decorator. Fix v1-compat tag-groups. Fix spec titles.

* fix: restore BasicAuth scheme definition for the users operations that reference them. Still need examples for these.

* fix: remove 1.x BasicAuth references where they don't belong.

* chore: sync from openapi master.

* fix: use replace-shortcodes to replace full Docs URLs in the contracts with absolute local paths to avoid roundtrips. Improve v1compat titles.

* Update api-docs/cloud/swaggerV1Compat.yml

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update api-docs/cloud/swaggerV1Compat.yml

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update api-docs/cloud/swaggerV1Compat.yml

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update api-docs/cloud/swaggerV1Compat.yml

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update api-docs/cloud/swaggerV1Compat.yml

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/3515/head
Jason Stirnaman 2021-12-21 14:34:49 -06:00 committed by GitHub
parent 02e180ef83
commit b100bbf256
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
21 changed files with 974 additions and 418 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
api-docs/.redocly.yaml
View File

@ -1,5 +1,4 @@
apiDefintions:
main: ref.yaml
lint:
plugins:
- './openapi/plugins/docs-plugin.js'

176
api-docs/cloud/ref.yml
View File

@ -728,6 +728,19 @@ components:
type: array
links:
$ref: '#/components/schemas/Links'
ColorMapping:
additionalProperties:
type: int
description: >-
A color mapping is an object that maps time series data to a UI color
scheme to allow the UI to render graphs consistent colors across
reloads.
example:
configcat_deployments-autopromotionblocker: 0
measurement_birdmigration_europe: 0
series_id_1: 0
series_id_2: 1
type: object
ColumnDataType:
enum:
- integer
@ -4502,6 +4515,39 @@ components:
type:
type: string
type: object
TelegrafPluginRequest:
properties:
config:
type: string
description:
type: string
metadata:
properties:
buckets:
items:
type: string
type: array
type: object
name:
type: string
orgID:
type: string
plugins:
items:
properties:
alias:
type: string
config:
type: string
description:
type: string
name:
type: string
type:
type: string
type: object
type: array
type: object
TelegrafPlugins:
properties:
os:
@ -5788,6 +5834,9 @@ components:
properties:
axes:
$ref: '#/components/schemas/Axes'
colorMapping:
$ref: '#/components/schemas/ColorMapping'
description: An object that contains information about the color mapping
colors:
description: Colors define color encoding of data into a visualization
items:
@ -5884,9 +5933,8 @@ components:
### Basic authentication scheme
Use the HTTP Basic authentication scheme with clients that support the
InfluxDB 1.x convention of username and password (that don't support the
`Authorization: Token` scheme):
Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API
operations that support it:
- **username**: InfluxDB Cloud username
- **password**: InfluxDB Cloud API token
@ -5902,86 +5950,43 @@ components:
with
- *`INFLUX_API_TOKEN`*: your [InfluxDB API
token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token)
For more information and examples, see how to [authenticate with a
username and
password](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/).
token](/influxdb/cloud/reference/glossary/#token)
scheme: basic
type: http
QuerystringAuthentication:
description: >
### Querystring authentication scheme
Use InfluxDB 1.x API parameters to provide credentials through the query
string.
Username and password schemes require the following credentials:
- **username**: InfluxDB Cloud username
- **password**: InfluxDB Cloud API token
#### Example
`curl --get "https://europe-west1-1.gcp.cloud2.influxdata.com/query"
--data-urlencode "u=exampleuser@influxdata.com"
--data-urlencode "p=INFLUX_API_TOKEN"`
Replace the following:
- *`exampleuser@influxdata.com`*: the email address that you signed up
with
- *`INFLUX_API_TOKEN`*: your [InfluxDB API
token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token)
For more information and examples, see how to [authenticate with a
username and password
scheme](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/).
in: query
name: u=&p=
type: apiKey
TokenAuthentication:
bearerFormat: InfluxDB token string
description: >
### Token authentication scheme
Use the [Token
authentication](#section/Authentication/TokenAuthentication)
scheme to authenticate to the InfluxDB API.
InfluxDB API tokens ensure secure interaction between users and data. A
token belongs to an organization and identifies InfluxDB permissions
within the organization.
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.
Include your API token in an `Authorization: Token INFLUX_TOKEN` HTTP
header with each request.
### Syntax
#### Example
`Authorization: Token YOUR_INFLUX_TOKEN`
`curl https://us-east-1-1.aws.cloud2.influxdata.com/
--header "Authorization: Token INFLUX_API_TOKEN"`
Replace *`INFLUX_API_TOKEN`* with your [InfluxDB API
token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token).
For more information and examples, see the following:
- [`/authorizations`](#tag/Authorizations) endpoint.
- [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication).
- [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens).
- [Assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token).
scheme: token
type: http
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/cloud/security/tokens).
in: header
name: Authorization
type: apiKey
info:
title: Influx Cloud API Service
title: InfluxDB Cloud API Service
description: >
The InfluxDB v2 API provides a programmatic interface for all interactions
with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.
@ -11213,7 +11218,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/TelegrafRequest'
$ref: '#/components/schemas/TelegrafPluginRequest'
description: Telegraf configuration to create
required: true
responses:
@ -11317,7 +11322,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/TelegrafRequest'
$ref: '#/components/schemas/TelegrafPluginRequest'
description: Telegraf configuration update to apply
required: true
responses:
@ -12364,20 +12369,16 @@ paths:
- Write
security:
- TokenAuthentication: []
- BasicAuthentication: []
- QuerystringAuthentication: []
servers:
- url: /
tags:
- description: >
Use one of the following schemes to authenticate to the InfluxDB API:
- description: |
The InfluxDB `/api/v2` API requires authentication for all requests.
Use InfluxDB API tokens to authenticate requests to the `/api/v2` API.
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring
authentication](#section/Authentication/QuerystringAuthentication)
For more information, see
[Token authentication](#section/Authentication/TokenAuthentication)
<!-- ReDoc-Inject: <security-definitions> -->
name: Authentication
@ -12390,9 +12391,9 @@ tags:
For more information and examples, see the following:
- [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication).
- [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens).
- [Assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token).
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/cloud/security/tokens).
- [Assign a token to a specific user](/influxdb/cloud/security/tokens/create-token).
name: Authorizations
- Bucket Schemas
- Buckets
@ -12413,16 +12414,14 @@ tags:
Retrieve data, analyze queries, and get query suggestions.
name: Query
- description: >
See the [**API Quick
Start**](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/)
to get up and running authenticating with tokens, writing to buckets, and
See the [**API Quick Start**](/influxdb/cloud/api-guide/api_intro/) to get
up and running authenticating with tokens, writing to buckets, and
querying data.
[**InfluxDB API client
libraries**](https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/)
are available for popular languages and ready to import into your
application.
libraries**](/influxdb/cloud/api-guide/client-libraries/) are available
for popular languages and ready to import into your application.
name: Quick start
x-traitTag: true
- Resources
@ -12457,8 +12456,7 @@ tags:
malformed</li><li>API token value is missing from the header</li><li>API
token does not have permission. For more information about token types and
permissions, see [Manage API
tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/)</li>
|
tokens](/influxdb/cloud/security/tokens/)</li> |
| `404` | Not found | Requested resource was not
found. `message` in the response body provides details about the requested

291
api-docs/cloud/swaggerV1Compat.yml
View File

@ -1,18 +1,24 @@
# this is a manually maintained file for these old routes until oats#15 is resolved
openapi: "3.0.0"
openapi: 3.0.0
info:
title: Influx API Service (V1 compatible endpoints)
title: InfluxDB Cloud v1 compatibility API documentation
version: 0.1.0
description: |
The InfluxDB 1.x compatibility `/write` and `/query` endpoints work with
InfluxDB 1.x client libraries and third-party integrations like Grafana
and others.
If you want to use the latest InfluxDB `/api/v2` API instead,
see the [InfluxDB v2 API documentation](/influxdb/cloud/api/).
servers:
- url: /
description: V1 compatible api endpoints.
paths:
/write:
post: # technically this functions with other methods as well
post:
operationId: PostWriteV1
tags:
- Write
summary: Write time series data into InfluxDB in a V1 compatible format
summary: Write time series data into InfluxDB in a V1-compatible format
requestBody:
description: Line protocol body
required: true
@ -21,15 +27,17 @@ paths:
schema:
type: string
parameters:
- $ref: "#/components/parameters/TraceSpan"
- $ref: "#/components/parameters/AuthUserV1"
- $ref: "#/components/parameters/AuthPassV1"
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
- $ref: '#/components/parameters/AuthPassV1'
- in: query
name: db
schema:
type: string
required: true
description: The bucket to write to. If none exist a bucket will be created with a default 3 day retention policy.
description: >-
Bucket to write to. If none exist a bucket will be created with
a default 3 day retention policy.
- in: query
name: rp
schema:
@ -42,54 +50,76 @@ paths:
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.
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.
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.
'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.
$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":
$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.
$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.
$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.
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.
'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.
description: >-
A non-negative decimal integer indicating the seconds to delay
after the response is received.
schema:
type: integer
format: int32
@ -98,9 +128,9 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
$ref: '#/components/schemas/Error'
/query:
post: # technically this functions with other methods as well
post:
operationId: PostQueryV1
tags:
- Query
@ -108,18 +138,21 @@ paths:
requestBody:
description: InfluxQL query to execute.
content:
text/plain: # although this should be `application/vnd.influxql`, oats breaks so we define the content-type header parameter
text/plain:
schema:
type: string
parameters:
- $ref: "#/components/parameters/TraceSpan"
- $ref: "#/components/parameters/AuthUserV1"
- $ref: "#/components/parameters/AuthPassV1"
- $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.
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
@ -128,10 +161,15 @@ paths:
- 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.
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.
description: >-
Specifies that the query response in the body should be encoded
with gzip or not encoded with identity.
default: identity
enum:
- gzip
@ -142,48 +180,70 @@ paths:
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":
'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
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.
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.
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"
$ref: '#/components/schemas/InfluxQLCSVResponse'
text/csv:
schema:
$ref: "#/components/schemas/InfluxQLCSVResponse"
$ref: '#/components/schemas/InfluxQLCSVResponse'
application/json:
schema:
$ref: "#/components/schemas/InfluxQLResponse"
$ref: '#/components/schemas/InfluxQLResponse'
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.
'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.
description: >-
A non-negative decimal integer indicating the seconds to delay
after the response is received.
schema:
type: integer
format: int32
@ -192,7 +252,7 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
$ref: '#/components/schemas/Error'
components:
parameters:
TraceSpan:
@ -200,8 +260,8 @@ components:
name: Zap-Trace-Span
description: OpenTracing span context
example:
trace_id: "1"
span_id: "1"
trace_id: '1'
span_id: '1'
baggage:
key: value
required: false
@ -260,7 +320,6 @@ components:
description: Code is the machine-readable error code.
readOnly: true
type: string
# This set of enumerations must remain in sync with the constants defined in errors.go
enum:
- internal error
- not found
@ -277,7 +336,9 @@ components:
readOnly: true
description: Message is a human-readable message.
type: string
required: [code, message]
required:
- code
- message
LineProtocolError:
properties:
code:
@ -297,18 +358,26 @@ components:
type: string
op:
readOnly: true
description: Op describes the logical code operation during error. Useful for debugging.
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.
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]
required:
- code
- message
- op
- err
LineProtocolLengthError:
properties:
code:
@ -326,4 +395,108 @@ components:
description: Max length in bytes for a body of line-protocol.
type: integer
format: int32
required: [code, message, maxLength]
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/).
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
- Query
- Write
x-tagGroups:
- name: Overview
tags:
- Authentication
- name: Data I/O endpoints
tags:
- Write
- Query
- name: All endpoints
tags:
- Query
- Write

6
api-docs/generate-api-docs.sh
View File

@ -67,6 +67,11 @@ weight: 304
--templateOptions.version="$version" \
--templateOptions.titleVersion="$titleVersion" \
# Use Redoc's openapi-cli to regenerate the v1-compat spec with custom decorations.
INFLUXDB_API_VERSION=v1compat INFLUXDB_VERSION=$version npm_config_yes=true npx $openapiCLI bundle $version/swaggerV1Compat.yml \
--config=./.redocly.yaml \
-o $version/swaggerV1Compat.yml
# Use Redoc to generate the v1 compatibility API html
npm_config_yes=true npx $redocCLI bundle $version/swaggerV1Compat.yml \
-t template.hbs \
@ -74,6 +79,7 @@ weight: 304
--options.sortPropsAlphabetically \
--options.menuToggle \
--options.hideHostname \
--options.noAutoAuth \
--templateOptions.version="$version" \
--templateOptions.titleVersion="$titleVersion" \
--output=redoc-static-v1-compat.html \

2
api-docs/getswagger.sh
View File

@ -98,7 +98,7 @@ function updateOSS {
}
function updateV1Compat {
echo "Updating Cloud and ${ossVersion} v1 compatibilty openapi..."
echo "Updating Cloud and ${ossVersion} v1 compatibility openapi..."
curl ${verbose} ${baseUrl}/contracts/swaggerV1Compat.yml -s -o cloud/swaggerV1Compat.yml
mkdir -p ${ossVersion} && cp cloud/swaggerV1Compat.yml $_/swaggerV1Compat.yml
}

2
api-docs/openapi/content/cloud/info.yml
View File

@ -1,3 +1,3 @@
title: Influx Cloud API Service
title: InfluxDB Cloud API Service
description: |
The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.

1
api-docs/openapi/content/cloud/v1compat/info.yml Normal file
View File

@ -0,0 +1 @@
title: InfluxDB Cloud v1 compatibility API documentation

9
api-docs/openapi/content/cloud/v1compat/tag-groups.yml Normal file
View File

@ -0,0 +1,9 @@
- name: Overview
tags:
- Authentication
- name: Data I/O endpoints
tags:
- Write
- Query
- name: All endpoints
tags: []

2
api-docs/openapi/content/content.js
View File

@ -2,7 +2,7 @@ const path = require('path');
const { toJSON } = require('../plugins/helpers/content-helper');
function getVersion(filename) {
return path.join(__dirname, process.env.INFLUXDB_VERSION, filename);
return path.join(__dirname, process.env.INFLUXDB_VERSION, (process.env.INFLUXDB_API_VERSION || ''), filename);
}
const info = toJSON(getVersion('info.yml'));

2
api-docs/openapi/content/v2.0/info.yml
View File

@ -1,3 +1,3 @@
title: Influx OSS API Service
title: InfluxDB OSS API Service
description: |
The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.

2
api-docs/openapi/content/v2.1/info.yml
View File

@ -1,3 +1,3 @@
title: Influx OSS API Service
title: InfluxDB OSS API Service
description: |
The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.

1
api-docs/openapi/content/v2.1/v1compat/info.yml Normal file
View File

@ -0,0 +1 @@
title: InfluxDB OSS v1 compatibility API documentation

9
api-docs/openapi/content/v2.1/v1compat/tag-groups.yml Normal file
View File

@ -0,0 +1,9 @@
- name: Overview
tags:
- Authentication
- name: Data I/O endpoints
tags:
- Write
- Query
- name: All endpoints
tags: []

42
api-docs/openapi/plugins/decorators/replace-shortcodes.js Normal file
View File

@ -0,0 +1,42 @@
module.exports = ReplaceShortcodes;
function replaceDocsUrl(node) {
const shortcode = /\{\{\% INFLUXDB_DOCS_URL \%\}\}/g;
let replacement = `/influxdb/${process.env.INFLUXDB_VERSION}`;
let description = node.description?.replace(shortcode, replacement);
const fullUrl = /https:\/\/docs\.influxdata\.com\/influxdb\//g;
replacement = "/influxdb/";
return description?.replace(fullUrl, replacement);
}
/** @type {import('@redocly/openapi-cli').OasDecorator} */
function docsUrl() {
return {
Info: {
leave(info, ctx) {
info.description = replaceDocsUrl(info);
}
},
PathItem: {
leave(pathItem, ctx) {
pathItem.description = replaceDocsUrl(pathItem);
}
},
Tag: {
leave(tag, ctx) {
tag.description = replaceDocsUrl(tag);
}
},
SecurityScheme: {
leave(scheme, ctx) {
scheme.description = replaceDocsUrl(scheme);
}
}
}
}
function ReplaceShortcodes() {
return {
docsUrl,
};
}

10
api-docs/openapi/plugins/decorators/set-info.js
View File

@ -6,9 +6,13 @@ function SetInfo(options) {
Info: {
leave(info, ctx) {
if(options.data) {
info.title = options.data.title;
info.description = options.data.description;
}
if(options.data.hasOwnProperty('title')) {
info.title = options.data.title;
}
if(options.data.hasOwnProperty('description')) {
info.description = options.data.description;
}
}
}
}
}

3
api-docs/openapi/plugins/docs-plugin.js
View File

@ -1,6 +1,7 @@
const ReportTags = require('./rules/report-tags');
const ValidateServersUrl = require('./rules/validate-servers-url');
const RemovePrivatePaths = require('./decorators/paths/remove-private-paths');
const ReplaceShortcodes = require('./decorators/replace-shortcodes');
const SetInfo = require('./decorators/set-info');
const SetServers = require('./decorators/servers/set-servers');
const SetSecuritySchemes = require('./decorators/security/set-security-schemes');
@ -24,6 +25,7 @@ const decorators = {
oas3: {
'set-servers': () => SetServers({data: servers}),
'remove-private-paths': RemovePrivatePaths,
'replace-docs-url-shortcode': ReplaceShortcodes().docsUrl,
'strip-version-prefix': StripVersionPrefix,
'set-info': () => SetInfo({data: info}),
'set-security': () => SetSecurity({data: security}),
@ -44,6 +46,7 @@ module.exports = {
decorators: {
'docs/set-servers': 'error',
'docs/remove-private-paths': 'error',
'docs/replace-docs-url-shortcode': 'error',
'docs/strip-version-prefix': 'error',
'docs/set-info': 'error',
'docs/set-tag-groups': 'error',

8
api-docs/openapi/plugins/helpers/content-helper.js
View File

@ -30,7 +30,7 @@ function sortName(a, b) {
function isPresent(collection, item) {
const itemName = getName(item);
return (
collection.indexOf(itemName) > -1
collection.indexOf(itemName) > -1
|| collection.filter(ci => ci.name && ci.name === itemName).length > 0
);
}
@ -42,7 +42,7 @@ function isPresent(collection, item) {
function collect(collection, items) {
if(Array.isArray(items)) {
collection = collection
.concat(items.filter(item => !isPresent(collection, item)));
.concat(items.filter(item => !isPresent(collection, item)));
}
return collection;
}
@ -51,7 +51,8 @@ function toJSON(yamlPath) {
try {
return yaml.load(fs.readFileSync(yamlPath, 'utf8'));
} catch (e) {
console.log(e);
/** No file, no harm, no foul. **/
// console.log(e);
}
}
@ -62,4 +63,3 @@ module.exports = {
sortName,
toJSON,
}

38
api-docs/v2.0/ref.yml
View File

@ -5844,15 +5844,14 @@ components:
- *`1.x_USERNAME`*: your InfluxDB v1.x username
- *`1.x_PASSWORD`*: your InfluxDB v1.x password
- *`1.x_PASSWORD`*: your InfluxDB v1.x password
- *`INFLUX_API_TOKEN`*: your [InfluxDB API
token](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#token)
token](/influxdb/v2.0/reference/glossary/#token)
For more information and examples, see how to [authenticate with a
username and password
scheme](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/)
username and password scheme](/influxdb/v2.0/reference/api/influxdb-1x/)
scheme: basic
type: http
QuerystringAuthentication:
@ -5886,15 +5885,14 @@ components:
- *`1.x_USERNAME`*: your InfluxDB v1.x username
- *`1.x_PASSWORD`*: your InfluxDB v1.x password
- *`1.x_PASSWORD`*: your InfluxDB v1.x password
- *`INFLUX_API_TOKEN`*: your [InfluxDB API
token](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#token)
token](/influxdb/v2.0/reference/glossary/#token)
For more information and examples, see how to [authenticate with a
username and
password](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x/)
username and password](/influxdb/v2.0/reference/api/influxdb-1x/)
in: query
name: u=&p=
type: apiKey
@ -5921,17 +5919,17 @@ components:
--header "Authorization: Token INFLUX_API_TOKEN"`
Replace *`INFLUX_API_TOKEN`* with your [InfluxDB API
token](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#token).
token](/influxdb/v2.0/reference/glossary/#token).
For more information and examples, see the following:
- [`/authorizations`](#tag/Authorizations) endpoint.
- [Use tokens in API requests](https://docs.influxdata.com/influxdb/v2.0/api-guide/api_intro/#authentication).
- [Manage API tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens).
- [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.0/security/tokens/create-token).
- [Use tokens in API requests](/influxdb/v2.0/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/v2.0/security/tokens).
- [Assign a token to a specific user](/influxdb/v2.0/security/tokens/create-token).
scheme: token
type: http
info:
title: Influx OSS API Service
title: InfluxDB OSS API Service
description: >
The InfluxDB v2 API provides a programmatic interface for all interactions
with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.
@ -12969,16 +12967,14 @@ tags:
- name: Quick start
x-traitTag: true
description: >
See the [**API Quick
Start**](https://docs.influxdata.com/influxdb/v2.0/api-guide/api_intro/)
to get up and running authenticating with tokens, writing to buckets, and
See the [**API Quick Start**](/influxdb/v2.0/api-guide/api_intro/) to get
up and running authenticating with tokens, writing to buckets, and
querying data.
[**InfluxDB API client
libraries**](https://docs.influxdata.com/influxdb/v2.0/api-guide/client-libraries/)
are available for popular languages and ready to import into your
application.
libraries**](/influxdb/v2.0/api-guide/client-libraries/) are available for
popular languages and ready to import into your application.
- Ready
- Resources
- name: Response codes
@ -13013,8 +13009,8 @@ tags:
following: <li>`Authorization: Token` header is missing or
malformed</li><li>API token value is missing from the header</li><li>API
token does not have permission. For more information about token types and
permissions, see [Manage API
tokens](https://docs.influxdata.com/influxdb/v2.0/security/tokens/)</li> |
permissions, see [Manage API tokens](/influxdb/v2.0/security/tokens/)</li>
|
| `404` | Not found | Requested resource was not
found. `message` in the response body provides details about the requested

289
api-docs/v2.0/swaggerV1Compat.yml
View File

@ -1,18 +1,24 @@
# this is a manually maintained file for these old routes until oats#15 is resolved
openapi: "3.0.0"
openapi: 3.0.0
info:
title: Influx API Service (V1 compatible endpoints)
version: 0.1.0
description: |
The InfluxDB 1.x compatibility /write and /query endpoints work with
InfluxDB 1.x client libraries and third-party integrations like Grafana
and others.
If you want to use the latest InfluxDB `/api/v2` API instead,
see the [InfluxDB v2 API documentation](/influxdb/v2.0/api).
servers:
- url: /
description: V1 compatible api endpoints.
paths:
/write:
post: # technically this functions with other methods as well
post:
operationId: PostWriteV1
tags:
- Write
summary: Write time series data into InfluxDB in a V1 compatible format
summary: Write time series data into InfluxDB in a V1 compatible format.
requestBody:
description: Line protocol body
required: true
@ -21,15 +27,17 @@ paths:
schema:
type: string
parameters:
- $ref: "#/components/parameters/TraceSpan"
- $ref: "#/components/parameters/AuthUserV1"
- $ref: "#/components/parameters/AuthPassV1"
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
- $ref: '#/components/parameters/AuthPassV1'
- in: query
name: db
schema:
type: string
required: true
description: The bucket to write to. If none exist a bucket will be created with a default 3 day retention policy.
description: >-
The bucket to write to. If none exist a bucket will be created with
a default 3 day retention policy.
- in: query
name: rp
schema:
@ -42,54 +50,76 @@ paths:
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.
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.
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.
'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.
$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":
$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.
$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.
$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.
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.
'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.
description: >-
A non-negative decimal integer indicating the seconds to delay
after the response is received.
schema:
type: integer
format: int32
@ -98,9 +128,9 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
$ref: '#/components/schemas/Error'
/query:
post: # technically this functions with other methods as well
post:
operationId: PostQueryV1
tags:
- Query
@ -108,18 +138,21 @@ paths:
requestBody:
description: InfluxQL query to execute.
content:
text/plain: # although this should be `application/vnd.influxql`, oats breaks so we define the content-type header parameter
text/plain:
schema:
type: string
parameters:
- $ref: "#/components/parameters/TraceSpan"
- $ref: "#/components/parameters/AuthUserV1"
- $ref: "#/components/parameters/AuthPassV1"
- $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.
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
@ -128,10 +161,15 @@ paths:
- 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.
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.
description: >-
Specifies that the query response in the body should be encoded
with gzip or not encoded with identity.
default: identity
enum:
- gzip
@ -142,48 +180,70 @@ paths:
type: string
enum:
- application/vnd.influxql
- in: query
name: db
schema:
type: string
required: true
description: The bucket to query.
- in: query
name: rp
schema:
type: string
description: The retention policy name.
- in: query
name: q
description: Defines the influxql query to run.
schema:
type: string
responses:
"200":
'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
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.
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.
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"
$ref: '#/components/schemas/InfluxQLCSVResponse'
text/csv:
schema:
$ref: "#/components/schemas/InfluxQLCSVResponse"
$ref: '#/components/schemas/InfluxQLCSVResponse'
application/json:
schema:
$ref: "#/components/schemas/InfluxQLResponse"
$ref: '#/components/schemas/InfluxQLResponse'
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.
'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.
description: >-
A non-negative decimal integer indicating the seconds to delay
after the response is received.
schema:
type: integer
format: int32
@ -192,7 +252,7 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
$ref: '#/components/schemas/Error'
components:
parameters:
TraceSpan:
@ -200,8 +260,8 @@ components:
name: Zap-Trace-Span
description: OpenTracing span context
example:
trace_id: "1"
span_id: "1"
trace_id: '1'
span_id: '1'
baggage:
key: value
required: false
@ -260,7 +320,6 @@ components:
description: Code is the machine-readable error code.
readOnly: true
type: string
# This set of enumerations must remain in sync with the constants defined in errors.go
enum:
- internal error
- not found
@ -277,7 +336,9 @@ components:
readOnly: true
description: Message is a human-readable message.
type: string
required: [code, message]
required:
- code
- message
LineProtocolError:
properties:
code:
@ -297,18 +358,26 @@ components:
type: string
op:
readOnly: true
description: Op describes the logical code operation during error. Useful for debugging.
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.
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]
required:
- code
- message
- op
- err
LineProtocolLengthError:
properties:
code:
@ -326,4 +395,108 @@ components:
description: Max length in bytes for a body of line-protocol.
type: integer
format: int32
required: [code, message, maxLength]
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/v2.1/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/v2.1/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/v2.1/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/v2.1/reference/api/influxdb-1x/).
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
- Query
- Write
x-tagGroups:
- name: Overview
tags:
- Authentication
- name: Data I/O endpoints
tags:
- Write
- Query
- name: All endpoints
tags:
- Query
- Write

207
api-docs/v2.1/ref.yml
View File

@ -794,6 +794,19 @@ components:
type: array
links:
$ref: '#/components/schemas/Links'
ColorMapping:
additionalProperties:
type: int
description: >-
A color mapping is an object that maps time series data to a UI color
scheme to allow the UI to render graphs consistent colors across
reloads.
example:
configcat_deployments-autopromotionblocker: 0
measurement_birdmigration_europe: 0
series_id_1: 0
series_id_2: 1
type: object
ConditionalExpression:
description: >-
Selects one of two expressions, `Alternate` or `Consequent`, depending
@ -4440,6 +4453,39 @@ components:
type:
type: string
type: object
TelegrafPluginRequest:
properties:
config:
type: string
description:
type: string
metadata:
properties:
buckets:
items:
type: string
type: array
type: object
name:
type: string
orgID:
type: string
plugins:
items:
properties:
alias:
type: string
config:
type: string
description:
type: string
name:
type: string
type:
type: string
type: object
type: array
type: object
TelegrafPlugins:
properties:
os:
@ -5717,6 +5763,9 @@ components:
properties:
axes:
$ref: '#/components/schemas/Axes'
colorMapping:
$ref: '#/components/schemas/ColorMapping'
description: An object that contains information about the color mapping
colors:
description: Colors define color encoding of data into a visualization
items:
@ -5810,123 +5859,49 @@ components:
securitySchemes:
BasicAuthentication:
description: >
### Basic authentication scheme
Use HTTP Basic Auth with clients that support the InfluxDB 1.x
convention of username and password (that don't support the
`Authorization: Token` scheme).
Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API
operations that support it.
Username and password schemes require the following credentials:
- **username**: 1.x username (this is separate from the UI login username)
- **password**: 1.x password or InfluxDB API token
#### API token example
`curl --get "http://localhost:8086/query"
--user "1.x_USERNAME":"INFLUX_API_TOKEN"`
#### 1.x password example
`curl --get "http://localhost:8086/query"
--user "1.x_USERNAME":"1.x_PASSWORD"`
Replace the following:
- *`1.x_USERNAME`*: your InfluxDB v1.x username
- *`1.x_PASSWORD`*: your InfluxDB v1.x password
- *`INFLUX_API_TOKEN`*: your [InfluxDB API
token](https://docs.influxdata.com/influxdb/v2.1/reference/glossary/#token)
For more information and examples, see how to [authenticate with a
username and password
scheme](https://docs.influxdata.com/influxdb/v2.1/reference/api/influxdb-1x/)
- **username**
- **password**
scheme: basic
type: http
QuerystringAuthentication:
description: >
### Querystring authentication scheme
Use InfluxDB 1.x API parameters to provide credentials through the query
string.
Username and password schemes require the following credentials:
- **username**: 1.x username (this is separate from the UI login username)
- **password**: 1.x password or InfluxDB API token
#### API token example
`curl --get "http://localhost:8086/query"
--data-urlencode "u=1.x_USERNAME"
--data-urlencode "p=INFLUX_API_TOKEN"`
#### 1.x password example
`curl --get "http://localhost:8086/query"
--data-urlencode "u=1.x_USERNAME"
--data-urlencode "p=1.x_PASSWORD"`
Replace the following:
- *`1.x_USERNAME`*: your InfluxDB v1.x username
- *`1.x_PASSWORD`*: your InfluxDB v1.x password
- *`INFLUX_API_TOKEN`*: your [InfluxDB API
token](https://docs.influxdata.com/influxdb/v2.1/reference/glossary/#token)
For more information and examples, see how to [authenticate with a
username and password
scheme](https://docs.influxdata.com/influxdb/v2.1/reference/api/influxdb-1x/)
in: query
name: u=&p=
type: apiKey
TokenAuthentication:
bearerFormat: InfluxDB Token String
description: >
### Token authentication scheme
Use the [Token
authentication](#section/Authentication/TokenAuthentication)
scheme to authenticate to the InfluxDB API.
InfluxDB API tokens enable authentication and authorization of API
clients.
A token belongs to an organization and identifies InfluxDB permissions
within the organization.
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.
Include your API token in an `Authorization: Token` HTTP header with
each request.
### Syntax
#### Example
`Authorization: Token YOUR_INFLUX_TOKEN`
`curl http://localhost:8086/ping
--header "Authorization: Token INFLUX_API_TOKEN"`
Replace *`INFLUX_API_TOKEN`* with your [InfluxDB API
token](https://docs.influxdata.com/influxdb/v2.1/reference/glossary/#token).
For more information and examples, see the following:
- [`/authorizations`](#tag/Authorizations) endpoint.
- [Authorize API requests](https://docs.influxdata.com/influxdb/v2.1/api-guide/api_intro/#authentication).
- [Manage API tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens).
- [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.1/security/tokens/create-token).
scheme: token
type: http
- [Authorize API requests](/influxdb/v2.1/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/v2.1/security/tokens/).
in: header
name: Authorization
type: apiKey
info:
title: Influx OSS API Service
title: InfluxDB OSS API Service
description: >
The InfluxDB v2 API provides a programmatic interface for all interactions
with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.
@ -11812,7 +11787,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/TelegrafRequest'
$ref: '#/components/schemas/TelegrafPluginRequest'
description: Telegraf configuration to create
required: true
responses:
@ -11916,7 +11891,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/TelegrafRequest'
$ref: '#/components/schemas/TelegrafPluginRequest'
description: Telegraf configuration update to apply
required: true
responses:
@ -12974,20 +12949,16 @@ paths:
- Write
security:
- TokenAuthentication: []
- BasicAuthentication: []
- QuerystringAuthentication: []
servers:
- url: /
tags:
- description: >
Use one of the following schemes to authenticate to the InfluxDB API:
- description: |
The InfluxDB `/api/v2` API requires authentication for all requests.
Use InfluxDB API tokens to authenticate requests to the `/api/v2` API.
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring
authentication](#section/Authentication/QuerystringAuthentication)
For examples and more information, see
[Token authentication](#section/Authentication/TokenAuthentication)
<!-- ReDoc-Inject: <security-definitions> -->
name: Authentication
@ -13000,9 +12971,9 @@ tags:
For more information and examples, see the following:
- [Authorize API requests](https://docs.influxdata.com/influxdb/v2.1/api-guide/api_intro/#authentication).
- [Manage API tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens).
- [Assign a token to a specific user](https://docs.influxdata.com/influxdb/v2.1/security/tokens/create-token).
- [Authorize API requests](/influxdb/v2.1/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/v2.1/security/tokens/).
- [Assign a token to a specific user](/influxdb/v2.1/security/tokens/create-token).
name: Authorizations
- Backup
- Buckets
@ -13022,16 +12993,14 @@ tags:
Retrieve data, analyze queries, and get query suggestions.
name: Query
- description: >
See the [**API Quick
Start**](https://docs.influxdata.com/influxdb/v2.1/api-guide/api_intro/)
to get up and running authenticating with tokens, writing to buckets, and
See the [**API Quick Start**](/influxdb/v2.1/api-guide/api_intro/) to get
up and running authenticating with tokens, writing to buckets, and
querying data.
[**InfluxDB API client
libraries**](https://docs.influxdata.com/influxdb/v2.1/api-guide/client-libraries/)
are available for popular languages and ready to import into your
application.
libraries**](/influxdb/v2.1/api-guide/client-libraries/) are available for
popular languages and ready to import into your application.
name: Quick start
x-traitTag: true
- Ready
@ -13066,8 +13035,8 @@ tags:
following: <li>`Authorization: Token` header is missing or
malformed</li><li>API token value is missing from the header</li><li>API
token does not have permission. For more information about token types and
permissions, see [Manage API
tokens](https://docs.influxdata.com/influxdb/v2.1/security/tokens/)</li> |
permissions, see [Manage API tokens](/influxdb/v2.1/security/tokens/)</li>
|
| `404` | Not found | Requested resource was not
found. `message` in the response body provides details about the requested

291
api-docs/v2.1/swaggerV1Compat.yml
View File

@ -1,18 +1,24 @@
# this is a manually maintained file for these old routes until oats#15 is resolved
openapi: "3.0.0"
openapi: 3.0.0
info:
title: Influx API Service (V1 compatible endpoints)
title: InfluxDB OSS v1 compatibility API documentation
version: 0.1.0
description: |
The InfluxDB 1.x compatibility /write and /query endpoints work with
InfluxDB 1.x client libraries and third-party integrations like Grafana
and others.
If you want to use the latest InfluxDB `/api/v2` API instead,
see the [InfluxDB v2 API documentation](/influxdb/v2.1/api/).
servers:
- url: /
description: V1 compatible api endpoints.
paths:
/write:
post: # technically this functions with other methods as well
post:
operationId: PostWriteV1
tags:
- Write
summary: Write time series data into InfluxDB in a V1 compatible format
summary: Write time series data into InfluxDB in a V1-compatible format
requestBody:
description: Line protocol body
required: true
@ -21,15 +27,17 @@ paths:
schema:
type: string
parameters:
- $ref: "#/components/parameters/TraceSpan"
- $ref: "#/components/parameters/AuthUserV1"
- $ref: "#/components/parameters/AuthPassV1"
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
- $ref: '#/components/parameters/AuthPassV1'
- in: query
name: db
schema:
type: string
required: true
description: The bucket to write to. If none exist a bucket will be created with a default 3 day retention policy.
description: >-
The bucket to write to. If none exist a bucket will be created with
a default 3 day retention policy.
- in: query
name: rp
schema:
@ -42,54 +50,76 @@ paths:
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.
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.
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.
'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.
$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":
$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.
$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.
$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.
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.
'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.
description: >-
A non-negative decimal integer indicating the seconds to delay
after the response is received.
schema:
type: integer
format: int32
@ -98,9 +128,9 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
$ref: '#/components/schemas/Error'
/query:
post: # technically this functions with other methods as well
post:
operationId: PostQueryV1
tags:
- Query
@ -108,18 +138,21 @@ paths:
requestBody:
description: InfluxQL query to execute.
content:
text/plain: # although this should be `application/vnd.influxql`, oats breaks so we define the content-type header parameter
text/plain:
schema:
type: string
parameters:
- $ref: "#/components/parameters/TraceSpan"
- $ref: "#/components/parameters/AuthUserV1"
- $ref: "#/components/parameters/AuthPassV1"
- $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.
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
@ -128,10 +161,15 @@ paths:
- 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.
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.
description: >-
Specifies that the query response in the body should be encoded
with gzip or not encoded with identity.
default: identity
enum:
- gzip
@ -142,48 +180,70 @@ paths:
type: string
enum:
- application/vnd.influxql
- in: query
name: db
schema:
type: string
required: true
description: The bucket to query.
- in: query
name: rp
schema:
type: string
description: The retention policy name.
- in: query
name: q
description: Defines the influxql query to run.
schema:
type: string
responses:
"200":
'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
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.
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.
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"
$ref: '#/components/schemas/InfluxQLCSVResponse'
text/csv:
schema:
$ref: "#/components/schemas/InfluxQLCSVResponse"
$ref: '#/components/schemas/InfluxQLCSVResponse'
application/json:
schema:
$ref: "#/components/schemas/InfluxQLResponse"
$ref: '#/components/schemas/InfluxQLResponse'
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.
'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.
description: >-
A non-negative decimal integer indicating the seconds to delay
after the response is received.
schema:
type: integer
format: int32
@ -192,7 +252,7 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
$ref: '#/components/schemas/Error'
components:
parameters:
TraceSpan:
@ -200,8 +260,8 @@ components:
name: Zap-Trace-Span
description: OpenTracing span context
example:
trace_id: "1"
span_id: "1"
trace_id: '1'
span_id: '1'
baggage:
key: value
required: false
@ -260,7 +320,6 @@ components:
description: Code is the machine-readable error code.
readOnly: true
type: string
# This set of enumerations must remain in sync with the constants defined in errors.go
enum:
- internal error
- not found
@ -277,7 +336,9 @@ components:
readOnly: true
description: Message is a human-readable message.
type: string
required: [code, message]
required:
- code
- message
LineProtocolError:
properties:
code:
@ -297,18 +358,26 @@ components:
type: string
op:
readOnly: true
description: Op describes the logical code operation during error. Useful for debugging.
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.
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]
required:
- code
- message
- op
- err
LineProtocolLengthError:
properties:
code:
@ -326,4 +395,108 @@ components:
description: Max length in bytes for a body of line-protocol.
type: integer
format: int32
required: [code, message, maxLength]
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/v2.1/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/v2.1/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/v2.1/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/v2.1/reference/api/influxdb-1x/).
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
- Query
- Write
x-tagGroups:
- name: Overview
tags:
- Authentication
- name: Data I/O endpoints
tags:
- Write
- Query
- name: All endpoints
tags:
- Query
- Write