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

Fix/api reference (#3977) 

* chore: add decorator to strip trailing slash from path URLs

* chore: openapi processing

- remove custom tags and revert to managing tags in influxdata/openapi.
- remove security scheme content; revert to managing in influxdata/openapi.
- delete unused decorator
- fix strip-version-prefix--replace regex
- revert to bold for h4-h6
- use docs-release/influxdb-oss release branch for OSS docs.
- update README

* Update api-docs/README.md

Co-authored-by: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com>

* chore: add instruction for updating the release branch.

* Update api-docs/README.md

* Update api-docs/README.md

* Update api-docs/README.md

* Update api-docs/README.md

* chore: update cloud API spec

- tag updates
- Invokable rename
- Cleanup.

* Update api-docs/README.md

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

Co-authored-by: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com>
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/3984/head^2
Jason Stirnaman 2022-04-26 17:16:36 -05:00 committed by GitHub
parent 0f0930961e
commit afbe39b8a2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
30 changed files with 871 additions and 1074 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
api-docs/README.md
View File

@ -1,4 +1,5 @@
## Generate InfluxDB API docs
# How to generate InfluxDB API docs
InfluxData uses [Redoc](https://github.com/Redocly/redoc/),
[redoc-cli](https://github.com/Redocly/redoc/blob/master/cli/README.md),
and Redocly's [OpenApi CLI](https://redoc.ly/docs/cli/) to generate
@ -9,10 +10,11 @@ not committed to the docs repo.
The InfluxDB docs deployment process uses OpenAPI specification files in the `api-docs` directory
to generate version-specific (Cloud, OSS v2.1, OSS v2.0, etc.) API documentation.
### Versioned OpenAPI files
## How we version OpenAPI contracts
The `api-docs` directory structure versions OpenAPI files using the following pattern:
```
```md
api-docs/
├── v2.0/
│ └── ref.yml
@ -26,7 +28,46 @@ api-docs/
└── etc...
```
### Fetch and process openapi contracts
### InfluxDB Cloud version
Because InfluxDB Cloud releases are frequent, we make no effort to version the
Cloud API spec. We regenerate API reference docs from `influxdata/openapi`
**master** as features are released.
### InfluxDB OSS version
Given that
`influxdata/openapi` **master** may contain OSS spec changes not implemented
in the current OSS release, we (Docs team) maintain a release branch, `influxdata/openapi`
**docs-release/influxdb-oss**, used to generate OSS reference docs.
To update this branch to a new OSS release, (re)base on the commit or tag for the [latest release of InfluxDB OSS](#how-to-find-the-api-spec-used-by-an-influxdb-oss-version).
```sh
git checkout docs-release/influxdb-oss
git rebase -i influxdb-oss-v2.2.0
git push -f origin docs-release/influxdb-oss
```
To update this branch with documentation changes between OSS releases, cherry-pick your documentation commits into the release branch.
```sh
git checkout docs-release/influxdb-oss
git cherry-pick <commit hashes>
git push -f origin docs-release/influxdb-oss
```
### How to find the API spec used by an InfluxDB OSS version
`influxdata/openapi` does not version the InfluxData API.
To find the `influxdata/openapi` commit SHA used in a specific version of InfluxDB OSS,
see `/scripts/fetch-swagger.sh` in `influxdata/influxdb`--for example,
for the `influxdata/openapi` commit used in OSS v2.2.0, see https://github.com/influxdata/influxdb/blob/v2.2.0/scripts/fetch-swagger.sh#L13=.
For convenience, we tag `influxdata/influxdb` (OSS) release points in `influxdata/openapi` as
`influxdb-oss-v[OSS_VERSION]`. See <https://github.com/influxdata/openapi/tags>.
## How to fetch and process influxdata/openapi contracts
Update the contracts in `api-docs` to the latest from `influxdata/openapi`.
```sh
@ -37,7 +78,8 @@ cd api-docs
sh getswagger.sh oss; sh getswagger.sh cloud
```
### Generate API docs locally
## How to generate API docs locally
Because the API documentation HTML is gitignored, you must manually generate it
to view the API docs locally.
@ -58,9 +100,44 @@ cd api-docs
sh generate-api-docs.sh
```
### Test your openapi spec edits
## How to use custom OpenAPI spec processing
Generally, you should manage API content in `influxdata/openapi`.
In some cases, however, you may want custom processing (e.g. collecting all Tags)
or additional content (e.g. describing the reference documentation)
specifically for the docs.
When you run `getswagger.sh`, it executes `@redocly/openapi-cli` and the plugins listed in `.redocly.yaml`.
[`./openapi/plugins`](./openapi/plugins) use
[`./openapi/plugins/decorators`](./openapi/plugins/decorators) to apply custom
processing to OpenAPI specs.
`.yml` files in [`./openapi/content`](./openapi/content) set content for sections (nodes) in the contract.
To update the content for those nodes, you only need to update the YAML files.
To add new YAML files for other nodes in the contracts,
configure the new content YAML file in [`./openapi/content/content.js`](./openapi/content/content.js).
The content structure and Markdown must be valid OAS.
Then, you'll need to write or update a decorator module for the node and configure the decorator in the plugin,
e.g. [`./openapi/plugins/docs-plugin.js`](`./openapi/plugins/docs-plugin.js).
See the [complete list of OAS v3.0 nodes](https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas3.ts#L529).
`@redocly/openapi-cli` requires that modules use CommonJS `require` syntax for imports.
### How to add tag content or describe a group of paths
In API reference docs, we use OpenAPI `tags` elements for navigation and the
`x-traitTag` vendor extension to define custom content.
| Example | OpenAPI field | |
|:-------------------------------------------------------------------------------------------------------|-------------------------------------------------------|--------------------------------------------|
| [Add supplementary documentation](https://docs.influxdata.com/influxdb/cloud/api/#tag/Quick-start) | `tags: [ { name: 'Quick start', x-traitTag: true } ]` | [Source](https://github.com/influxdata/openapi/master/src/cloud/tags.yml) |
| [Group and describe related paths](https://docs.influxdata.com/influxdb/cloud/api/#tag/Authorizations) | `tags: [ { name: 'Buckets', description: '...' } ]` | [Source](https://github.com/influxdata/openapi/master/src/cloud/tags-groups.yml)) |
## How to test your spec or API reference changes
You can use `getswagger.sh` to fetch contracts from any URL.
For example, if you've made changes to spec files and generated new contracts in your local `openapi` repo, you can use `getswagger.sh` to fetch and process them.
For example, if you've made changes to spec files and generated new contracts in your local `openapi` repo, run `getswagger.sh` to fetch and process them.
To fetch contracts from your own `openapi` repo, pass the
`-b` `base_url` option and the full path to your `openapi` directory.
@ -72,22 +149,14 @@ sh getswagger.sh oss -b file:///Users/me/github/openapi
After you fetch them, run the linter or generate HTML to test your changes before you commit them to `influxdata/openapi`.
By default, `getswagger.sh` doesn't run the linter when bundling
the specs. Manually run the [linter rules](https://redoc.ly/docs/cli/resources/built-in-rules/) to get a report of errors and warnings.
the specs.
Manually run the [linter rules](https://redoc.ly/docs/cli/resources/built-in-rules/) to get a report of errors and warnings.
```sh
npx @redocly/openapi-cli lint v2.1/ref.yml
```
### Configure OpenAPI CLI linting and bundling
The `.redoc.yaml` configuration file sets options for the `@redocly/openapi-cli` [`lint`](https://redoc.ly/docs/cli/commands/lint/) and [`bundle`](https://redoc.ly/docs/cli/commands/bundle/) commands.
`./openapi/plugins` contains custom InfluxData Docs plugins composed of *rules* (for validating and linting) and *decorators* (for customizing). For more configuration options, see `@redocly/openapi-cli` [configuration file documentation](https://redoc.ly/docs/cli/configuration/configuration-file/).
### Custom content
`./openapi/content` contains custom OAS (OpenAPI Spec) content in YAML files. The content structure and Markdown must be valid OAS.
`./openapi/plugins` use `./openapi/plugins/decorators` to apply the content to the contracts.
`.yml` files in `./openapi/content/` set content for sections (nodes) in the contract. To update the content for those nodes, you only need to update the YAML files.
To add new YAML files for other nodes in the openapi contracts, configure the new content YAML file in `./openapi/content/content.js`. Then, write a decorator module for the node and configure the decorator in the plugin, e.g. `./openapi/plugins/docs-plugin.js`. See the [complete list of OAS v3.0 nodes](https://github.com/Redocly/openapi-cli/blob/master/packages/core/src/types/oas3.ts#L529).
`@redocly/openapi-cli` requires that modules use CommonJS `require` syntax for imports.

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

@ -602,6 +602,7 @@ components:
latest scheduled and completed run.
format: date-time
readOnly: true
type: string
links:
example:
labels: /api/v2/checks/1/labels
@ -3274,6 +3275,13 @@ components:
type: string
name:
type: string
users:
description: >-
An optional list of email address's to be invited to the
organization
items:
type: string
type: array
required:
- name
type: object
@ -3895,6 +3903,7 @@ components:
ScriptInvocationParams:
properties:
params:
additionalProperties: true
type: object
type: object
ScriptLanguage:
@ -5782,6 +5791,8 @@ components:
- stacked
- bar
- monotoneX
- stepBefore
- stepAfter
type: string
XYViewProperties:
properties:
@ -7225,9 +7236,7 @@ paths:
required: true
schema:
type: string
- description: >-
Includes the cell view properties in the response if set to
`properties`
- description: If `properties`, includes the cell view properties in the response.
in: query
name: include
required: false
@ -7256,7 +7265,7 @@ paths:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Retrieve a Dashboard
summary: Retrieve a dashboard
tags:
- Dashboards
patch:
@ -9548,10 +9557,13 @@ paths:
- Usage
/ping:
get:
description: Returns the status and InfluxDB version of the instance.
operationId: GetPing
responses:
'204':
description: OK
description: |
OK.
Headers contain InfluxDB version information.
headers:
X-Influxdb-Build:
description: The type of InfluxDB build.
@ -9561,16 +9573,18 @@ paths:
description: The version of InfluxDB.
schema:
type: integer
servers:
- url: ''
summary: Checks the status of InfluxDB instance and version of InfluxDB.
servers: []
summary: Get the status and version of the instance
tags:
- Ping
head:
description: Returns the status and InfluxDB version of the instance.
operationId: HeadPing
responses:
'204':
description: OK
description: |
OK.
Headers contain InfluxDB version information.
headers:
X-Influxdb-Build:
description: The type of InfluxDB build.
@ -9580,9 +9594,8 @@ paths:
description: The version of InfluxDB.
schema:
type: integer
servers:
- url: ''
summary: Checks the status of InfluxDB instance and version of InfluxDB.
servers: []
summary: Get the status and version of the instance
tags:
- Ping
/api/v2/query:
@ -9633,16 +9646,16 @@ paths:
- application/vnd.flux
type: string
- description: >-
Specifies the name of the organization executing the query. Takes
either the ID or Name. If both `orgID` and `org` are specified,
`org` takes precedence.
Name of the organization executing the query. Accepts either the ID
or Name. If you provide both `orgID` and `org`, `org` takes
precedence.
in: query
name: org
schema:
type: string
- description: >-
Specifies the ID of the organization executing the query. If both
`orgID` and `org` are specified, `org` takes precedence.
ID of the organization executing the query. If you provide both
`orgID` and `org`, `org` takes precedence.
in: query
name: orgID
schema:
@ -9663,10 +9676,6 @@ paths:
responses:
'200':
content:
application/vnd.influx.arrow:
schema:
format: binary
type: string
text/csv:
schema:
example: >
@ -9684,28 +9693,33 @@ paths:
schema:
default: identity
description: >
The content coding: `gzip` for compressed data or `identity`
for unmodified, uncompressed data.
Content coding: `gzip` for compressed data or `identity` for
unmodified, uncompressed data.
enum:
- gzip
- identity
type: string
Trace-Id:
description: >-
The Trace-Id header reports the request's trace ID, if one was
generated.
description: If generated, trace ID of the request.
schema:
description: Specifies the request's trace ID.
description: Trace ID of a request.
type: string
'429':
description: >-
Token is temporarily over quota. The Retry-After header describes
when to try the read again.
description: |
#### InfluxDB Cloud:
- returns this error if a **read** or **write** request exceeds your
plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#adjustable-service-quotas)
or if a **delete** request exceeds the maximum
[global limit](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#global-limits)
- returns `Retry-After` header that describes when to try the write again.
#### InfluxDB OSS:
- doesn't return this error.
headers:
Retry-After:
description: >-
A non-negative decimal integer indicating the seconds to delay
after the response is received.
Non-negative decimal integer indicating seconds to wait before
retrying the request.
schema:
format: int32
type: integer
@ -9893,7 +9907,7 @@ paths:
description: Unexpected error
summary: List scripts
tags:
- Invocable Scripts
- Invokable Scripts
post:
operationId: PostScripts
requestBody:
@ -9915,7 +9929,7 @@ paths:
description: Unexpected error
summary: Create a script
tags:
- Invocable Scripts
- Invokable Scripts
/api/v2/scripts/{scriptID}:
delete:
description: Deletes a script and all associated records.
@ -9935,9 +9949,9 @@ paths:
description: Unexpected error
summary: Delete a script
tags:
- Invocable Scripts
- Invokable Scripts
get:
description: Uses script ID to retrieve details of an invocable script.
description: Uses script ID to retrieve details of an invokable script.
operationId: GetScriptsID
parameters:
- description: The script ID.
@ -9958,10 +9972,10 @@ paths:
description: Unexpected error
summary: Retrieve a script
tags:
- Invocable Scripts
- Invokable Scripts
patch:
description: >
Updates properties (`name`, `description`, and `script`) of an invocable
Updates properties (`name`, `description`, and `script`) of an invokable
script.
operationId: PatchScriptsID
parameters:
@ -9990,7 +10004,7 @@ paths:
description: Unexpected error
summary: Update a script
tags:
- Invocable Scripts
- Invokable Scripts
/api/v2/scripts/{scriptID}/invoke:
post:
description: >-
@ -10020,7 +10034,7 @@ paths:
description: Unexpected error
summary: Invoke a script
tags:
- Invocable Scripts
- Invokable Scripts
/api/v2/setup:
get:
description: >-
@ -12025,108 +12039,129 @@ paths:
Writes data to a bucket.
To write data into InfluxDB, you need the following:
Use this endpoint to send data in [line
protocol](https://docs.influxdata.com/influxdb/cloud/reference/syntax/line-protocol/)
format to InfluxDB.
InfluxDB parses and validates line protocol in the request body,
responds with success or failure, and then handles the write
asynchronously.
- **organization name or ID** – _See [View
organizations](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/#view-your-organization-id)
for instructions on viewing your organization ID._
- **bucket** – _See [View
buckets](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/view-buckets/)
for
instructions on viewing your bucket ID._
- **API token** – _See [View
tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/)
for instructions on viewing your API token._
- **InfluxDB URL** – _See [InfluxDB
URLs](https://docs.influxdata.com/influxdb/cloud/reference/urls/)_.
- data in [line
protocol](https://docs.influxdata.com/influxdb/cloud/reference/syntax/line-protocol)
format.
#### Required permissions
InfluxDB Cloud enforces rate and size limits different from InfluxDB
OSS. For details, see Responses.
- `write-buckets` or `write-bucket BUCKET_ID`
For more information and examples, see the following:
`BUCKET_ID` is the ID of the destination bucket.
#### Rate limits (with InfluxDB Cloud)
`write` rate limits apply.
For more information, see [limits and adjustable
quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/).
#### Related guides
- [Write data with the InfluxDB
API](https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/api).
- [Optimize writes to
InfluxDB](https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/optimize-writes/).
- [Troubleshoot issues writing
data](https://docs.influxdata.com/influxdb/cloud/write-data/troubleshoot/)
operationId: PostWrite
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: >
The value tells InfluxDB what compression is applied to the line
protocol in the request payload.
To make an API request with a GZIP payload, send `Content-Encoding:
gzip` as a request header.
- description: |
The compression applied to the line protocol in the request payload.
To send a GZIP payload, pass `Content-Encoding: gzip` header.
in: header
name: Content-Encoding
schema:
default: identity
description: >-
The content coding. Use `gzip` for compressed data or `identity`
for unmodified, uncompressed data.
description: >
Content coding.
Use `gzip` for compressed data or `identity` for unmodified,
uncompressed data.
enum:
- gzip
- identity
type: string
- description: >-
The header value indicates the format of the data in the request
body.
- description: >
The format of the data in the request body.
To send a line protocol payload, pass `Content-Type: text/plain;
charset=utf-8`.
in: header
name: Content-Type
schema:
default: text/plain; charset=utf-8
description: >
`text/plain` specifies line protocol. `UTF-8` is the default
character set.
`text/plain` is the content type for line protocol. `UTF-8` is the
default character set.
enum:
- text/plain
- text/plain; charset=utf-8
- application/vnd.influx.arrow
type: string
- description: >-
The header value indicates the size of the entity-body, in bytes,
sent to the database. If the length is greater than the database's
`max body` configuration option, the server responds with status
code `413`.
- description: |
The size of the entity-body, in bytes, sent to InfluxDB.
If the length is greater than the `max body` configuration option,
the server responds with status code `413`.
in: header
name: Content-Length
schema:
description: The length in decimal number of octets.
type: integer
- description: The header value specifies the response format.
- description: |
The content type that the client can understand.
Writes only return a response body if they fail--for example,
due to a formatting problem or quota limit.
#### InfluxDB Cloud
- Returns only `application/json` for format and limit errors.
- Returns only `text/html` for some quota limit errors.
#### InfluxDB OSS
- Returns only `application/json` for format and limit errors.
#### Related guides
- [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/cloud/write-data/troubleshoot/).
in: header
name: Accept
schema:
default: application/json
description: The response format for errors.
description: Error content type.
enum:
- application/json
type: string
- description: >-
The parameter value specifies the destination organization for
writes. The database writes all points in the batch to this
organization. If you provide both `orgID` and `org` parameters,
`org` takes precedence.
- description: >
The destination organization for writes.
The database writes all points in the batch to this organization.
If you provide both `orgID` and `org` parameters, `org` takes
precedence.
in: query
name: org
required: true
schema:
description: Organization name or ID.
description: The organization name or ID.
type: string
- description: >-
The parameter value specifies the ID of the destination organization
for writes. If both `orgID` and `org` are specified, `org` takes
precedence.
- description: |
The ID of the destination organization for writes.
If both `orgID` and `org` are specified, `org` takes precedence.
in: query
name: orgID
schema:
@ -12136,9 +12171,9 @@ paths:
name: bucket
required: true
schema:
description: All points within batch are written to this bucket.
description: InfluxDB writes all points in the batch to this bucket.
type: string
- description: The precision for the unix timestamps within the body line-protocol.
- description: The precision for unix timestamps in the line protocol batch.
in: query
name: precision
schema:
@ -12146,24 +12181,59 @@ paths:
requestBody:
content:
text/plain:
examples:
plain-utf8:
value: >
airSensors,sensor_id=TLM0201
temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615
1630424257000000000
airSensors,sensor_id=TLM0202
temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826
1630424257000000000
schema:
format: byte
type: string
description: Data in line protocol format.
description: >
Data in line protocol format.
To send compressed data, do the following:
1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data.
2. In your request, send the compressed data and the
`Content-Encoding: gzip` header.
#### Related guides
- [Best practices for optimizing
writes](https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/optimize-writes/).
required: true
responses:
'204':
description: >-
InfluxDB validated the request data format and accepted the data for
writing to the bucket. `204` doesn't indicate a successful write
operation since writes are asynchronous. See [how to check for write
description: >
Success. InfluxDB validated the request and the data format and
accepted the data for writing to the bucket.
Because data is written to InfluxDB asynchronously, data may not yet
be written to a bucket.
#### Related guides
- [How to check for write
errors](https://docs.influxdata.com/influxdb/cloud/write-data/troubleshoot/).
'400':
content:
application/json:
examples:
measurementSchemaFieldTypeConflict:
summary: Field type conflict thrown by an explicit bucket schema
summary: >-
InfluxDB Cloud field type conflict thrown by an explicit
bucket schema
value:
code: invalid
message: >-
@ -12174,9 +12244,9 @@ paths:
schema; got String but expected Float
schema:
$ref: '#/components/schemas/LineProtocolError'
description: >-
Bad request. The line protocol data in the request is malformed. The
response body contains the first malformed line in the data.
description: |
Bad request. The line protocol data in the request is malformed.
The response body contains the first malformed line in the data.
InfluxDB rejected the batch and did not write any data.
'401':
content:
@ -12237,26 +12307,39 @@ paths:
</html>
schema:
type: string
description: >
The request payload is too large. InfluxDB rejected the batch and
did not write any data.
description: |
The request payload is too large.
InfluxDB rejected the batch and did not write any data.
#### InfluxDB Cloud:
- returns this error if the payload exceeds the 50MB size limit.
- returns `Content-Type: text/html` for this error.
- Returns this error if the payload exceeds the 50MB size limit.
- Returns `Content-Type: text/html` for this error.
#### InfluxDB OSS:
- returns this error only if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error.
- returns `Content-Type: application/json` for this error.
- Returns this error only if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error.
- Returns `Content-Type: application/json` for this error.
'429':
description: >-
InfluxDB Cloud only. The token is temporarily over quota. The
Retry-After header describes when to try the write again.
description: |
Too many requests.
#### InfluxDB Cloud
- Returns this error if a **read** or **write** request exceeds your
plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#adjustable-service-quotas)
or if a **delete** request exceeds the maximum
[global limit](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#global-limits).
- Returns `Retry-After` header that describes when to try the write again.
#### InfluxDB OSS
- Doesn't return this error.
headers:
Retry-After:
description: >-
A non-negative decimal integer indicating the seconds to delay
after the response is received.
Non-negative decimal integer indicating seconds to wait before
retrying the request.
schema:
format: int32
type: integer
@ -12272,14 +12355,25 @@ paths:
$ref: '#/components/schemas/Error'
description: Internal server error.
'503':
description: >-
The server is temporarily unavailable to accept writes. The
`Retry-After` header describes when to try the write again.
description: |
Service unavailable.
#### InfluxDB Cloud
- Returns this error if series cardinality exceeds your plan's
[adjustable service quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#adjustable-service-quotas).
See [how to resolve high series cardinality](https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/resolve-high-cardinality/).
#### InfluxDB OSS
- Returns this error if
the server is temporarily unavailable to accept writes.
- Returns `Retry-After` header that 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.
Non-negative decimal integer indicating seconds to wait before
retrying the request.
schema:
format: int32
type: integer
@ -12293,43 +12387,111 @@ security:
servers:
- url: /
tags:
- description: |
The InfluxDB `/api/v2` API requires authentication for all requests.
Use InfluxDB API tokens to authenticate requests to the `/api/v2` API.
- description: >
Use one of the following schemes to authenticate to the InfluxDB API:
For more information, see
[Token authentication](#section/Authentication/TokenAuthentication)
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring
authentication](#section/Authentication/QuerystringAuthentication)
<!-- ReDoc-Inject: <security-definitions> -->
name: Authentication
x-traitTag: true
- description: >
Create and manage API tokens. An **authorization** associates a list of
permissions to an **organization** and provides a token for API access.
Create and manage API tokens.
An **authorization** associates a list of permissions to an
**organization** and provides a token for API access.
Optionally, you can restrict an authorization and its token to a specific
user.
For more information and examples, see the following:
### Related guides
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/cloud/security/tokens/).
- [Assign a token to a specific user](/influxdb/cloud/security/tokens/create-token/).
name: Authorizations
- Bucket Schemas
- Buckets
- Cells
- Checks
- Dashboards
- DBRPs
- Delete
- Invocable Scripts
- Labels
- Limits
- NotificationEndpoints
- NotificationRules
- Organizations
- Ping
- name: Bucket Schemas
- name: Buckets
- name: Cells
- name: Checks
- name: Dashboards
- name: DBRPs
- name: Delete
- description: >
InfluxDB API endpoints use standard HTTP request and response headers.
**Note**: Not all operations support all headers.
### Request headers
| Header | Value type |
Description |
|:------------------------ |:---------------------
|:-------------------------------------------|
| `Accept` | string | The content type that
the client can understand. |
| `Authorization` | string | The authorization
scheme and credential. |
| `Content-Encoding` | string | The compression
applied to the line protocol in the request payload. |
| `Content-Length` | integer | The size of the
entity-body, in bytes, sent to the database. |
| `Content-Type` | string | The format of the
data in the request body. |
name: Headers
x-traitTag: true
- description: >
Manage and execute scripts as API endpoints in InfluxDB.
An API Invokable Script assigns your custom Flux script to a new
InfluxDB API endpoint for your organization.
Invokable scripts let you execute your script as an HTTP request to the
endpoint.
Invokable scripts accept parameters.
Add parameter references in your script as `params.myparameter`.
When you `invoke` your script, you send parameters as key-value pairs in
the `params` object.
Then, InfluxDB executes your script with the key-value pairs as arguments,
and returns the result.
### Related guides
- [Invoke custom
scripts](/influxdb/cloud/api-guide/api-invokable-scripts/).
name: Invokable Scripts
- name: Labels
- name: Limits
- name: NotificationEndpoints
- name: NotificationRules
- name: Organizations
- name: Ping
- description: |
Retrieve data, analyze queries, and get query suggestions.
name: Query
@ -12344,7 +12506,7 @@ tags:
for popular languages and ready to import into your application.
name: Quick start
x-traitTag: true
- Resources
- name: Resources
- description: >
The InfluxDB API uses standard HTTP status codes for success and failure
responses.
@ -12399,20 +12561,20 @@ tags:
when to try the request again. |
name: Response codes
x-traitTag: true
- Routes
- Rules
- Secrets
- Setup
- Signin
- Signout
- Tasks
- Telegraf Plugins
- Telegrafs
- Templates
- Usage
- Users
- Variables
- Views
- name: Routes
- name: Rules
- name: Secrets
- name: Setup
- name: Signin
- name: Signout
- name: Tasks
- name: Telegraf Plugins
- name: Telegrafs
- name: Templates
- name: Usage
- name: Users
- name: Variables
- name: Views
- description: |
Write time series data to buckets.
name: Write
@ -12421,11 +12583,14 @@ x-tagGroups:
tags:
- Quick start
- Authentication
- Headers
- Response codes
- name: Data I/O endpoints
tags:
- Write
- Query
- Invokable Scripts
- Tasks
- name: Resource endpoints
tags:
- Buckets
@ -12451,7 +12616,7 @@ x-tagGroups:
- Dashboards
- DBRPs
- Delete
- Invocable Scripts
- Invokable Scripts
- Labels
- Limits
- NotificationEndpoints

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

@ -486,8 +486,8 @@ tags:
<!-- ReDoc-Inject: <security-definitions> -->
x-traitTag: true
- Query
- Write
- name: Query
- name: Write
x-tagGroups:
- name: Overview
tags:

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

@ -51,6 +51,7 @@ weight: 304
npx --version
# Use Redoc to generate the v2 API html
echo "Bundling ${version}/ref.yml"
npm_config_yes=true npx $redocCLI bundle $version/ref.yml \
-t template.hbs \
--title="InfluxDB $titleVersion API documentation" \
@ -62,6 +63,7 @@ weight: 304
--templateOptions.titleVersion="$titleVersion" \
# Use Redoc to generate the v1 compatibility API html
echo "Bundling ${version}/swaggerV1Compat.yml"
npm_config_yes=true npx $redocCLI bundle $version/swaggerV1Compat.yml \
-t template.hbs \
--title="InfluxDB $titleVersion v1 compatibility API documentation" \

16
api-docs/getswagger.sh
View File

@ -11,12 +11,14 @@
# - a base URL using the -b flag.
# The baseURL specifies where to retrieve the openapi files from.
# The default baseUrl is the master branch of the influxdata/openapi repo.
# The default baseUrl for OSS is the tag for the latest InfluxDB release.
# When a new OSS version is released, update baseUrlOSS to with the tag (/influxdb-oss-[SEMANTIC_VERSION]).
# For local development, pass your openapi directory using the file:/// protocol.
#
# Syntax:
# sh ./getswagger.sh <context>
# sh ./getswagger.sh <context> -b <baseUrl>
# sh .getswagger.sh -c <context> -o <version> -b <baseUrl>
# sh ./getswagger.sh -c <context> -o <version> -b <baseUrl>
#
# Examples:
# sh ./getswagger.sh cloud
@ -25,6 +27,7 @@
versionDirs=($(ls -d */))
latestOSS=${versionDirs[${#versionDirs[@]}-1]}
baseUrl="https://raw.githubusercontent.com/influxdata/openapi/master"
baseUrlOSS="https://raw.githubusercontent.com/influxdata/openapi/docs-release/influxdb-oss"
ossVersion=${latestOSS%/}
verbose=""
context=""
@ -63,6 +66,7 @@ case "$subcommand" in
;;
b)
baseUrl=$OPTARG
baseUrlOSS=$OPTARG
;;
o)
ossVersion=$OPTARG
@ -100,25 +104,25 @@ function postProcess() {
npx --version
# Use Redoc's openapi-cli to regenerate the spec with custom decorations.
INFLUXDB_API_VERSION=$apiVersion INFLUXDB_VERSION=$version npm_config_yes=true npx $openapiCLI bundle $specPath \
INFLUXDB_API_VERSION=$apiVersion \
INFLUXDB_VERSION=$version \
npm_config_yes=true \
npx $openapiCLI bundle $specPath \
--config=./.redocly.yaml \
-o $specPath
}
function updateCloud {
echo "Updating Cloud openapi..."
curl ${verbose} ${baseUrl}/contracts/ref/cloud.yml -s -o cloud/ref.yml
postProcess $_ cloud
}
function updateOSS {
echo "Updating OSS ${ossVersion} openapi..."
mkdir -p ${ossVersion} && curl ${verbose} ${baseUrl}/contracts/ref/oss.yml -s -o $_/ref.yml
mkdir -p ${ossVersion} && curl ${verbose} ${baseUrlOSS}/contracts/ref/oss.yml -s -o $_/ref.yml
postProcess $_ $ossVersion
}
function updateV1Compat {
echo "Updating Cloud and ${ossVersion} v1 compatibility openapi..."
curl ${verbose} ${baseUrl}/contracts/swaggerV1Compat.yml -s -o cloud/swaggerV1Compat.yml
postProcess $_ cloud v1compat

56
api-docs/openapi/content/cloud/security-schemes.yml
View File

@ -1,56 +0,0 @@
TokenAuthentication:
type: http
scheme: token
bearerFormat: InfluxDB Token String
description: |
### Token authentication scheme
InfluxDB API tokens ensure secure interaction between users and data. A token belongs to an organization and identifies InfluxDB permissions within the organization.
Include your API token in an `Authorization: Token YOUR_API_TOKEN` HTTP header with each request.
### Example
`curl https://us-east-1-1.aws.cloud2.influxdata.com/
--header "Authorization: Token YOUR_API_TOKEN"`
For more information and examples, see the following:
- [Use tokens in API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication).
- [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens).
- [`/authorizations`](#tag/Authorizations) endpoint.
BasicAuthentication:
type: http
scheme: basic
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):
- **username**: InfluxDB Cloud username
- **password**: InfluxDB Cloud API token
### Example
`curl --get "https://europe-west1-1.gcp.cloud2.influxdata.com/query"
--user "YOUR_USERNAME":"YOUR_TOKEN_OR_PASSWORD"`
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/).
QuerystringAuthentication:
type: apiKey
in: query
name: u=&p=
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=YOUR_USERNAME"
--data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"`
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/).

26
api-docs/openapi/content/cloud/tag-groups.yml
View File

@ -1,26 +0,0 @@
- name: Overview
tags:
- Quick start
- Authentication
- Response codes
- name: Data I/O endpoints
tags:
- Write
- Query
- name: Resource endpoints
tags:
- Buckets
- Dashboards
- Tasks
- Resources
- name: Security and access endpoints
tags:
- Authorizations
- Organizations
- Users
- name: System information endpoints
tags:
- Ping
- Routes
- name: All endpoints
tags: []

55
api-docs/openapi/content/cloud/tags.yml
View File

@ -1,55 +0,0 @@
- name: Authentication
description: |
Use one of the following schemes to authenticate to the InfluxDB API:
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
<!-- ReDoc-Inject: <security-definitions> -->
x-traitTag: true
- name: Invokable Scripts
description: |
Manage and execute scripts as API endpoints in InfluxDB.
An API Invokable Script assigns your custom Flux script to a new InfluxDB API endpoint for your organization.
Invokable scripts let you execute your script as an HTTP request to the endpoint.
Invokable scripts accept parameters. Add parameter references in your script as `params.myparameter`.
When you `invoke` your script, you send parameters as key-value pairs in the `params` object.
Then, InfluxDB executes your script with the key-value pairs as arguments, and returns the result.
For more information and examples, see [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts).
- name: Quick start
x-traitTag: true
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 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.
- name: Response codes
x-traitTag: true
description: |
The InfluxDB API uses standard HTTP status codes for success and failure responses.
The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation.
API operations may return the following HTTP status codes:
| &nbsp;Code&nbsp; | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. |
| `400` | Bad request | `Authorization` header is missing or malformed or the API token does not have permission for the operation. |
| `401` | Unauthorized | May indicate one of the 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/cloud/security/tokens/)</li> |
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
| `413` | Request entity too large | Request payload exceeds the size limit. |
| `422` | Unprocessible entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
| `500` | Internal server error | |
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
- name: Query
description: |
Retrieve data, analyze queries, and get query suggestions.
- name: Write
description: |
Write time series data to buckets.
- name: Authorizations
description: |
Create and manage API tokens. An **authorization** associates a list of permissions to an **organization** and provides a token for API access. To assign a token to a specific user, scope the authorization to the user ID.

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

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

58
api-docs/openapi/content/v2.0/security-schemes.yml
View File

@ -1,58 +0,0 @@
TokenAuthentication:
type: http
scheme: token
bearerFormat: InfluxDB Token String
description: |
### Token authentication scheme
InfluxDB API tokens ensure secure interaction between users and data. A token belongs to an organization and identifies InfluxDB permissions within the organization.
Include your API token in an `Authorization: Token YOUR_API_TOKEN` HTTP header with each request.
### Example
`curl http://localhost:8086/ping
--header "Authorization: Token YOUR_API_TOKEN"`
For more information and examples, see the following:
- [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).
- [`/authorizations`](#tag/Authorizations) endpoint.
BasicAuthentication:
type: http
scheme: basic
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).
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
### Example
`curl --get "http://localhost:8086/query"
--user "YOUR_1.x_USERNAME":"YOUR_TOKEN_OR_PASSWORD"`
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/)
QuerystringAuthentication:
type: apiKey
in: query
name: u=&p=
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
### Example
`curl --get "http://localhost:8086/query"
--data-urlencode "u=YOUR_1.x_USERNAME"
--data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"`
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/)

28
api-docs/openapi/content/v2.0/tag-groups.yml
View File

@ -1,28 +0,0 @@
- name: Overview
tags:
- Quick start
- Authentication
- Response codes
- name: Data I/O endpoints
tags:
- Write
- Query
- name: Resource endpoints
tags:
- Buckets
- Dashboards
- Tasks
- Resources
- name: Security and access endpoints
tags:
- Authorizations
- Organizations
- Users
- name: System information endpoints
tags:
- Health
- Ping
- Ready
- Routes
- name: All endpoints
tags: []

43
api-docs/openapi/content/v2.0/tags.yml
View File

@ -1,43 +0,0 @@
- name: Authentication
description: |
Use one of the following schemes to authenticate to the InfluxDB API:
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
<!-- ReDoc-Inject: <security-definitions> -->
x-traitTag: true
- 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 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.
- name: Response codes
x-traitTag: true
description: |
The InfluxDB API uses standard HTTP status codes for success and failure responses.
The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation.
API operations may return the following HTTP status codes:
| &nbsp;Code&nbsp; | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. |
| `400` | Bad request | `Authorization` header is missing or malformed or the API token does not have permission for the operation. |
| `401` | Unauthorized | May indicate one of the 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> |
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
| `413` | Request entity too large | Request payload exceeds the size limit. |
| `422` | Unprocessible entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
| `500` | Internal server error | |
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
- name: Query
description: |
Retrieve data, analyze queries, and get query suggestions.
- name: Write
description: |
Write time series data to buckets.
- name: Authorizations
description: |
Create and manage API tokens. An **authorization** associates a list of permissions to an **organization** and provides a token for API access. To assign a token to a specific user, scope the authorization to the user ID.

58
api-docs/openapi/content/v2.1/security-schemes.yml
View File

@ -1,58 +0,0 @@
TokenAuthentication:
type: http
scheme: token
bearerFormat: InfluxDB Token String
description: |
### Token authentication scheme
InfluxDB API tokens ensure secure interaction between users and data. A token belongs to an organization and identifies InfluxDB permissions within the organization.
Include your API token in an `Authentication: Token YOUR_API_TOKEN` HTTP header with each request.
### Example
`curl http://localhost:8086/ping
--header "Authentication: Token YOUR_API_TOKEN"`
For more information and examples, see the following:
- [Use tokens in 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).
- [`/authorizations`](#tag/Authorizations) endpoint.
BasicAuthentication:
type: http
scheme: basic
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).
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
### Example
`curl --get "http://localhost:8086/query"
--user "YOUR_1.x_USERNAME":"YOUR_TOKEN_OR_PASSWORD"`
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/)
QuerystringAuthentication:
type: apiKey
in: query
name: u=&p=
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
### Example
`curl --get "http://localhost:8086/query"
--data-urlencode "u=YOUR_1.x_USERNAME"
--data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"`
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/)

31
api-docs/openapi/content/v2.1/tag-groups.yml
View File

@ -1,31 +0,0 @@
- name: Overview
tags:
- Quick start
- Authentication
- Response codes
- name: Data I/O endpoints
tags:
- Write
- Query
- name: Resource endpoints
tags:
- Buckets
- Dashboards
- Tasks
- Resources
- name: Security and access endpoints
tags:
- Authorizations
- Organizations
- Users
- name: System information endpoints
tags:
- Config
- Debug
- Health
- Metrics
- Ping
- Ready
- Routes
- name: All endpoints
tags: []

43
api-docs/openapi/content/v2.1/tags.yml
View File

@ -1,43 +0,0 @@
- name: Authentication
description: |
Use one of the following schemes to authenticate to the InfluxDB API:
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
<!-- ReDoc-Inject: <security-definitions> -->
x-traitTag: true
- name: Quick start
x-traitTag: true
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 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.
- name: Response codes
x-traitTag: true
description: |
The InfluxDB API uses standard HTTP status codes for success and failure responses.
The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation.
API operations may return the following HTTP status codes:
| &nbsp;Code&nbsp; | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. |
| `400` | Bad request | `Authorization` header is missing or malformed or the API token does not have permission for the operation. |
| `401` | Unauthorized | May indicate one of the 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> |
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
| `413` | Request entity too large | Request payload exceeds the size limit. |
| `422` | Unprocessible entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
| `500` | Internal server error | |
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
- name: Query
description: |
Retrieve data, analyze queries, and get query suggestions.
- name: Write
description: |
Write time series data to buckets.
- name: Authorizations
description: |
Create and manage API tokens. An **authorization** associates a list of permissions to an **organization** and provides a token for API access. To assign a token to a specific user, scope the authorization to the user ID.

58
api-docs/openapi/content/v2.2/security-schemes.yml
View File

@ -1,58 +0,0 @@
TokenAuthentication:
type: http
scheme: token
bearerFormat: InfluxDB Token String
description: |
### Token authentication scheme
InfluxDB API tokens ensure secure interaction between users and data. A token belongs to an organization and identifies InfluxDB permissions within the organization.
Include your API token in an `Authentication: Token YOUR_API_TOKEN` HTTP header with each request.
### Example
`curl http://localhost:8086/ping
--header "Authentication: Token YOUR_API_TOKEN"`
For more information and examples, see the following:
- [Use tokens in 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).
- [`/authorizations`](#tag/Authorizations) endpoint.
BasicAuthentication:
type: http
scheme: basic
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).
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
### Example
`curl --get "http://localhost:8086/query"
--user "YOUR_1.x_USERNAME":"YOUR_TOKEN_OR_PASSWORD"`
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/)
QuerystringAuthentication:
type: apiKey
in: query
name: u=&p=
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
### Example
`curl --get "http://localhost:8086/query"
--data-urlencode "u=YOUR_1.x_USERNAME"
--data-urlencode "p=YOUR_TOKEN_OR_PASSWORD"`
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/)

31
api-docs/openapi/content/v2.2/tag-groups.yml
View File

@ -1,31 +0,0 @@
- name: Overview
tags:
- Quick start
- Authentication
- Response codes
- name: Data I/O endpoints
tags:
- Write
- Query
- name: Resource endpoints
tags:
- Buckets
- Dashboards
- Tasks
- Resources
- name: Security and access endpoints
tags:
- Authorizations
- Organizations
- Users
- name: System information endpoints
tags:
- Config
- Debug
- Health
- Metrics
- Ping
- Ready
- Routes
- name: All endpoints
tags: []

43
api-docs/openapi/content/v2.2/tags.yml
View File

@ -1,43 +0,0 @@
- name: Authentication
description: |
Use one of the following schemes to authenticate to the InfluxDB API:
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
<!-- ReDoc-Inject: <security-definitions> -->
x-traitTag: true
- name: Quick start
x-traitTag: true
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 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.
- name: Response codes
x-traitTag: true
description: |
The InfluxDB API uses standard HTTP status codes for success and failure responses.
The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation.
API operations may return the following HTTP status codes:
| &nbsp;Code&nbsp; | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. |
| `400` | Bad request | `Authorization` header is missing or malformed or the API token does not have permission for the operation. |
| `401` | Unauthorized | May indicate one of the 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> |
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
| `413` | Request entity too large | Request payload exceeds the size limit. |
| `422` | Unprocessible entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
| `500` | Internal server error | |
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
- name: Query
description: |
Retrieve data, analyze queries, and get query suggestions.
- name: Write
description: |
Write time series data to buckets.
- name: Authorizations
description: |
Create and manage API tokens. An **authorization** associates a list of permissions to an **organization** and provides a token for API access. To assign a token to a specific user, scope the authorization to the user ID.

18
api-docs/openapi/plugins/decorators/paths/strip-trailing-slash.js Normal file
View File

@ -0,0 +1,18 @@
module.exports = StripVersionPrefix;
/** @type {import('@redocly/openapi-cli').OasDecorator} */
function StripVersionPrefix() {
return {
PathMap: {
leave(paths, ctx) {
Object.keys(paths).forEach(function(p) {
if(p.length > 1 && p.endsWith('/')) {
const props = JSON.stringify(paths[p]);
paths[p.slice(0, -1)] = JSON.parse(props);
delete paths[p];
}
});
}
}
}
}

1
api-docs/openapi/plugins/decorators/paths/strip-version-prefix.js
View File

@ -6,6 +6,7 @@ function StripVersionPrefix() {
PathMap: {
leave(paths, ctx) {
const nonversioned = [
'/debug',
'/health',
'/legacy/authorizations',
'/legacy/authorizations/{authID}',

50
api-docs/openapi/plugins/decorators/replace-shortcodes.js
View File

@ -1,37 +1,41 @@
module.exports = ReplaceShortcodes;
function replaceDocsUrl(node) {
const shortcode = /\{\{\% INFLUXDB_DOCS_URL \%\}\}/g;
function replaceDocsUrl(field) {
if(!field) { return }
const shortcode = '{{% INFLUXDB_DOCS_URL %}}';
let replacement = `/influxdb/${process.env.INFLUXDB_VERSION}`;
let description = node.description?.replace(shortcode, replacement);
const fullUrl = /https:\/\/docs\.influxdata\.com\/influxdb\//g;
let replaced = field.replaceAll(shortcode, replacement);
const fullUrl = 'https://docs.influxdata.com/influxdb/';
replacement = "/influxdb/";
return description?.replace(fullUrl, replacement);
return replaced.replaceAll(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);
DefinitionRoot: {
Info: {
leave(info, ctx) {
info.description = replaceDocsUrl(info.description);
},
},
PathItem: {
leave(pathItem, ctx) {
pathItem.description = replaceDocsUrl(pathItem.description);
}
},
Tag: {
leave(tag, ctx) {
tag.description = replaceDocsUrl(tag.description);
}
},
SecurityScheme: {
leave(scheme, ctx) {
scheme.description = replaceDocsUrl(scheme.description);
}
}
}
}
}

22
api-docs/openapi/plugins/decorators/security/set-security-schemes.js
View File

@ -1,22 +0,0 @@
module.exports = SetSecuritySchemes;
const { securitySchemes } = require('../../../content/content')
/** @type {import('@redocly/openapi-cli').OasDecorator} */
function SetSecuritySchemes() {
const data = securitySchemes();
return {
Components: {
leave(comps, ctx) {
if(data) {
comps.securitySchemes = comps.securitySchemes || {};
Object.keys(data).forEach(
function(scheme) {
comps.securitySchemes[scheme] = data[scheme];
}
)
}
}
}
}
}

57
api-docs/openapi/plugins/decorators/tags/set-tag-groups.js
View File

@ -11,41 +11,50 @@ const { collect, getName, sortName } = require('../../helpers/content-helper.js'
* operation ('get', 'post', etc.) in every path.
* The DefinitionRoot handler, executed when
* the parser is leaving the root node,
* sets `x-tagGroups` to the provided `data`
* adds custom `tagGroups` content to `x-tagGroups`
* and sets the value of `All Endpoints` to the collected tags.
*/
/** @type {import('@redocly/openapi-cli').OasDecorator} */
function SetTagGroups() {
const data = tagGroups();
let data = tagGroups();
if(!Array.isArray(data)) {
data = [];
}
let tags = [];
/** Collect tags for each operation and convert string tags to object tags. **/
return {
Operation: {
leave(op, ctx, parents) {
let opTags = op.tags?.map(
function(t) {
return typeof t === 'string' ? { name: t, description: '' } : t;
}
) || [];
tags = collect(tags, opTags);
}
},
DefinitionRoot: {
Operation: {
leave(op) {
let opTags = op.tags?.map(
function(t) {
return typeof t === 'string' ? { name: t } : t;
}
) || [];
tags = collect(tags, opTags);
}
},
leave(root) {
root.tags = root.tags || [];
root.tags = collect(root.tags, tags)
.sort((a, b) => sortName(a, b));
root.tags = root.tags || [];
root.tags = collect(root.tags, tags)
.sort((a, b) => sortName(a, b));
if(!data) { return; }
endpointTags = root.tags
.filter(t => !t['x-traitTag'])
.map(t => getName(t));
endpointTags = root.tags
.filter(t => !t['x-traitTag'])
.map(t => getName(t));
root['x-tagGroups'] = data
.map(function(grp) {
grp.tags = grp.name === 'All endpoints' ? endpointTags : grp.tags;
return grp;
});
if(Array.isArray(root['x-tagGroups'])) {
root['x-tagGroups'].concat(data);
} else {
root['x-tagGroups'] = data;
}
root['x-tagGroups'].map(
function(grp) {
grp.tags = grp.name === 'All endpoints' ? endpointTags : grp.tags;
return grp;
});
}
}
}

5
api-docs/openapi/plugins/decorators/tags/set-tags.js
View File

@ -11,10 +11,11 @@ const { tags } = require('../../../content/content')
/** @type {import('@redocly/openapi-cli').OasDecorator} */
function SetTags() {
const data = tags();
let tags = [];
return {
DefinitionRoot: {
leave(root) {
/** Set tags from custom tags when visitor enters root. */
enter(root) {
if(data) {
root.tags = data;
}

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

@ -5,10 +5,9 @@ const ReplaceShortcodes = require('./decorators/replace-shortcodes');
const SetInfo = require('./decorators/set-info');
const DeleteServers = require('./decorators/servers/delete-servers');
const SetServers = require('./decorators/servers/set-servers');
const SetSecuritySchemes = require('./decorators/security/set-security-schemes');
const SetTags = require('./decorators/tags/set-tags');
const SetTagGroups = require('./decorators/tags/set-tag-groups');
const StripVersionPrefix = require('./decorators/paths/strip-version-prefix');
const StripTrailingSlash = require('./decorators/paths/strip-trailing-slash');
const id = 'docs';
@ -26,13 +25,11 @@ const decorators = {
'set-servers': SetServers,
'delete-servers': DeleteServers,
'remove-private-paths': RemovePrivatePaths,
'replace-docs-url-shortcode': ReplaceShortcodes().docsUrl,
'strip-version-prefix': StripVersionPrefix,
'strip-trailing-slash': StripTrailingSlash,
'set-info': SetInfo,
// 'set-security': SetSecurity,
'set-security-schemes': SetSecuritySchemes,
'set-tags': SetTags,
'set-tag-groups': SetTagGroups,
'replace-docs-url-shortcode': ReplaceShortcodes().docsUrl,
}
};
@ -48,10 +45,11 @@ module.exports = {
'docs/set-servers': 'error',
'docs/delete-servers': 'error',
'docs/remove-private-paths': 'error',
'docs/replace-docs-url-shortcode': 'error',
'docs/strip-version-prefix': 'error',
'docs/strip-trailing-slash': 'error',
'docs/set-info': 'error',
'docs/set-tag-groups': 'error',
'docs/replace-docs-url-shortcode': 'error',
},
},
},

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

@ -7142,27 +7142,6 @@ paths:
summary: Retrieve a check query
tags:
- Checks
/api/v2/config:
get:
operationId: GetConfig
parameters:
- $ref: '#/components/parameters/TraceSpan'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Config'
description: >-
Payload body contains the run-time configuration of the InfluxDB
instance.
'401':
$ref: '#/components/responses/ServerError'
default:
$ref: '#/components/responses/ServerError'
summary: Get the run-time configuration of the instance
tags:
- Config
/api/v2/dashboards:
get:
operationId: GetDashboards
@ -13699,8 +13678,6 @@ x-tagGroups:
- Users
- name: System information endpoints
tags:
- Config
- Debug
- Health
- Metrics
- Ping
@ -13713,7 +13690,6 @@ x-tagGroups:
- Buckets
- Cells
- Checks
- Config
- Dashboards
- DBRPs
- Delete

588
api-docs/v2.2/ref.yml
View File

File diff suppressed because it is too large Load Diff

20
api-docs/v2.2/swaggerV1Compat.yml
View File

@ -3,13 +3,13 @@ info:
title: InfluxDB OSS v1 compatibility API documentation
version: 0.1.0
description: |
The InfluxDB 1.x compatibility /write and /query endpoints work with
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/).
see the [InfluxDB v2 API documentation](/influxdb/cloud/api/).
servers:
- url: /
paths:
@ -36,8 +36,8 @@ paths:
type: string
required: true
description: >-
Bucket to write to. If none exist a bucket will be created with a
default 3 day retention policy.
Bucket to write to. If none exists, InfluxDB creates a bucket with a
default 3-day retention policy.
- in: query
name: rp
schema:
@ -430,8 +430,8 @@ components:
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/).
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/cloud/security/tokens/).
BasicAuthentication:
type: http
scheme: basic
@ -445,7 +445,7 @@ components:
For examples and more information, see how to [authenticate with a
username and password](/influxdb/v2.1/reference/api/influxdb-1x/).
username and password](/influxdb/cloud/reference/api/influxdb-1x/).
QuerystringAuthentication:
type: apiKey
in: query
@ -460,7 +460,7 @@ components:
For examples and more information, see how to [authenticate with a
username and password](/influxdb/v2.1/reference/api/influxdb-1x/).
username and password](/influxdb/cloud/reference/api/influxdb-1x/).
security:
- TokenAuthentication: []
- BasicAuthentication: []
@ -486,8 +486,8 @@ tags:
<!-- ReDoc-Inject: <security-definitions> -->
x-traitTag: true
- Query
- Write
- name: Query
- name: Write
x-tagGroups:
- name: Overview
tags:

2
assets/styles/layouts/_api-overrides.scss
View File

@ -103,7 +103,7 @@ $bold: 700;
}
#redoc {
h1,h2,h3,h4,h5,h6 {
h1,h2,h3 {
font-weight: $medium !important;
}
}

2
content/influxdb/v2.2/write-data/developer-tools/scrape-prometheus-metrics.md
View File

@ -1,6 +1,6 @@
---
title: Scrape Prometheus metrics
seotitle: Scape Prometheus metrics into InfluxDB
seotitle: Scrape Prometheus metrics into InfluxDB
weight: 205
description: >
Use Telegraf, InfluxDB scrapers, or the `prometheus.scrape` Flux function to