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

4788 build the http api reference for iox relevant endpoints (#4801) 

* feature(cloud-iox): add cloud-iox API reference content.

* feature(api): revise tagging, add cloud-iox API:

- Closes #4788.
- Generates cloud-iox/api.
- Changes handling of tags and x-tagGroups.
- Configures custom All Endpoints list for cloud-iox.
- Simplifies the nav with other grouping tags.
Any custom x-tagGroups configured in
[platform]/content/tag-groups.yml take precedence over
those already defined in the spec.
If you assign a list of tags to 'All endpoints' x-tagGroup,
the decorator
will use that list and remove Operations not tagged with
those tags.
If you assign an empty array([]) to the 'All endpoints' x-tagGroup,
the decorator will list all resource-like tags.
TODO: document in CONTRIBUTING.
TODO: unset x-tagGroups from openapi.

* Apply suggestions from code review

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

---------

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/4802/head
Jason Stirnaman 2023-03-15 10:20:56 -05:00 committed by GitHub
parent aeae2888e1
commit da6c2e467d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 17154 additions and 25212 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
api-docs/cloud-iox/content/info.yml Normal file
View File

@ -0,0 +1,11 @@
title: InfluxDB Cloud (IOx) API Service
description: |
The InfluxDB HTTP API provides a programmatic interface for all interactions with InfluxDB.
Access the InfluxDB API using the `/api/v2/` endpoint.
This documentation is generated from the
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml).
version: Cloud 2.x
license:
name: MIT
url: 'https://opensource.org/licenses/MIT'

8
api-docs/cloud-iox/content/servers.yml Normal file
View File

@ -0,0 +1,8 @@
- url: https://{baseurl}
description: InfluxDB Cloud (IOx) API URL
variables:
baseurl:
enum:
- 'us-east-1-1.aws.cloud2.influxdata.com'
default: 'us-east-1-1.aws.cloud2.influxdata.com'
description: InfluxDB Cloud (IOx) URL

33
api-docs/cloud-iox/content/tag-groups.yml Normal file
View File

@ -0,0 +1,33 @@
- name: Using the InfluxDB HTTP API
tags:
- Quick start
- Authentication
- Supported operations
- Headers
- Pagination
- Response codes
- Data I/O endpoints
- Security and access endpoints
- System information endpoints
- name: All endpoints
tags:
- Authorizations (API tokens)
- Bucket Schemas
- Buckets
- Delete
- DBRPs
- Invokable Scripts
- Legacy Query
- Legacy Write
- Limits
- Organizations
- Query
- Resources
- Routes
- Secrets
- Tasks
- Telegrafs
- Templates
- Usage
- Variables
- Write

11
api-docs/cloud-iox/content/v1compat/info.yml Normal file
View File

@ -0,0 +1,11 @@
title: InfluxDB Cloud IOx v1 compatibility API documentation
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/).
This documentation is generated from the
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
license:
name: MIT
url: 'https://opensource.org/licenses/MIT'

16195
api-docs/cloud-iox/ref.yml Normal file
View File

File diff suppressed because it is too large Load Diff

432
api-docs/cloud-iox/swaggerV1Compat.yml Normal file
View File

@ -0,0 +1,432 @@
openapi: 3.0.0
info:
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/).
This documentation is generated from the
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: /
paths:
/write:
post:
operationId: PostWriteV1
tags:
- Write
summary: Write time series data into InfluxDB in a V1-compatible format
requestBody:
description: Line protocol body
required: true
content:
text/plain:
schema:
type: string
parameters:
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
- $ref: '#/components/parameters/AuthPassV1'
- in: query
name: db
schema:
type: string
required: true
description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy.
- in: query
name: rp
schema:
type: string
description: Retention policy name.
- in: query
name: precision
schema:
type: string
description: Write precision.
- in: header
name: Content-Encoding
description: When present, its value indicates to the database that compression is applied to the line protocol body.
schema:
type: string
description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
responses:
'204':
description: Write data is correctly formatted and accepted for writing to the bucket.
'400':
description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
content:
application/json:
schema:
$ref: '#/components/schemas/LineProtocolError'
'401':
description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: No token was sent and they are required.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'413':
description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.
content:
application/json:
schema:
$ref: '#/components/schemas/LineProtocolLengthError'
'429':
description: Token is temporarily over quota. The Retry-After header describes when to try the write again.
headers:
Retry-After:
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
schema:
type: integer
format: int32
'503':
description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again.
headers:
Retry-After:
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
schema:
type: integer
format: int32
default:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/query:
post:
operationId: PostQueryV1
tags:
- Query
summary: Query InfluxDB in a V1 compatible format
requestBody:
description: InfluxQL query to execute.
content:
text/plain:
schema:
type: string
parameters:
- $ref: '#/components/parameters/TraceSpan'
- $ref: '#/components/parameters/AuthUserV1'
- $ref: '#/components/parameters/AuthPassV1'
- in: header
name: Accept
schema:
type: string
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
default: application/json
enum:
- application/json
- application/csv
- text/csv
- application/x-msgpack
- in: header
name: Accept-Encoding
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
schema:
type: string
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
- in: header
name: Content-Type
schema:
type: string
enum:
- application/vnd.influxql
- in: query
name: db
schema:
type: string
required: true
description: Bucket to query.
- in: query
name: rp
schema:
type: string
description: Retention policy name.
- in: query
name: q
description: Defines the influxql query to run.
schema:
type: string
responses:
'200':
description: Query results
headers:
Content-Encoding:
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
schema:
type: string
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
default: identity
enum:
- gzip
- identity
Trace-Id:
description: The Trace-Id header reports the request's trace ID, if one was generated.
schema:
type: string
description: Specifies the request's trace ID.
content:
application/csv:
schema:
$ref: '#/components/schemas/InfluxQLCSVResponse'
text/csv:
schema:
$ref: '#/components/schemas/InfluxQLCSVResponse'
application/json:
schema:
$ref: '#/components/schemas/InfluxQLResponse'
application/x-msgpack:
schema:
type: string
format: binary
'429':
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
headers:
Retry-After:
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
schema:
type: integer
format: int32
default:
description: Error processing query
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
TraceSpan:
in: header
name: Zap-Trace-Span
description: OpenTracing span context
example:
trace_id: '1'
span_id: '1'
baggage:
key: value
required: false
schema:
type: string
AuthUserV1:
in: query
name: u
required: false
schema:
type: string
description: Username.
AuthPassV1:
in: query
name: p
required: false
schema:
type: string
description: User token.
schemas:
InfluxQLResponse:
properties:
results:
type: array
oneOf:
- required:
- statement_id
- error
- required:
- statement_id
- series
items:
type: object
properties:
statement_id:
type: integer
error:
type: string
series:
type: array
items:
type: object
properties:
name:
type: string
tags:
type: object
additionalProperties:
type: string
partial:
type: boolean
columns:
type: array
items:
type: string
values:
type: array
items:
type: array
items: {}
InfluxQLCSVResponse:
type: string
example: |
name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value
Error:
properties:
code:
description: Code is the machine-readable error code.
readOnly: true
type: string
enum:
- internal error
- not found
- conflict
- invalid
- unprocessable entity
- empty value
- unavailable
- forbidden
- too many requests
- unauthorized
- method not allowed
message:
readOnly: true
description: Message is a human-readable message.
type: string
required:
- code
- message
LineProtocolError:
properties:
code:
description: Code is the machine-readable error code.
readOnly: true
type: string
enum:
- internal error
- not found
- conflict
- invalid
- empty value
- unavailable
message:
readOnly: true
description: Message is a human-readable message.
type: string
op:
readOnly: true
description: Op describes the logical code operation during error. Useful for debugging.
type: string
err:
readOnly: true
description: Err is a stack of errors that occurred during processing of the request. Useful for debugging.
type: string
line:
readOnly: true
description: First line within sent body containing malformed data
type: integer
format: int32
required:
- code
- message
- op
- err
LineProtocolLengthError:
properties:
code:
description: Code is the machine-readable error code.
readOnly: true
type: string
enum:
- invalid
message:
readOnly: true
description: Message is a human-readable message.
type: string
maxLength:
readOnly: true
description: Max length in bytes for a body of line-protocol.
type: integer
format: int32
required:
- code
- message
- maxLength
securitySchemes:
TokenAuthentication:
type: apiKey
name: Authorization
in: header
description: |
Use the [Token authentication](#section/Authentication/TokenAuthentication)
scheme to authenticate to the InfluxDB API.
In your API requests, send an `Authorization` header.
For the header value, provide the word `Token` followed by a space and an InfluxDB API token.
The word `Token` is case-sensitive.
### Syntax
`Authorization: Token YOUR_INFLUX_TOKEN`
For examples and more information, see the following:
- [`/authorizations`](#tag/Authorizations) endpoint.
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
- [Manage API tokens](/influxdb/cloud/security/tokens/).
BasicAuthentication:
type: http
scheme: basic
description: |
Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication)
scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
QuerystringAuthentication:
type: apiKey
in: query
name: u=&p=
description: |
Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication)
scheme with InfluxDB 1.x API parameters to provide credentials through the query string.
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
security:
- TokenAuthentication: []
- BasicAuthentication: []
- QuerystringAuthentication: []
tags:
- name: Authentication
description: |
The InfluxDB 1.x API requires authentication for all requests.
InfluxDB Cloud uses InfluxDB API tokens to authenticate requests.
For more information, see the following:
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
<!-- ReDoc-Inject: <security-definitions> -->
x-traitTag: true
- name: Query
- name: Write
x-tagGroups: []

13
api-docs/cloud/content/tag-groups.yml Normal file
View File

@ -0,0 +1,13 @@
- name: Using the InfluxDB HTTP API
tags:
- Quick start
- Authentication
- Supported operations
- Headers
- Pagination
- Response codes
- Data I/O endpoints
- Security and access endpoints
- System information endpoints
- name: All endpoints
tags: []

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

File diff suppressed because it is too large Load Diff

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

@ -429,4 +429,3 @@ tags:
x-traitTag: true
- name: Query
- name: Write
x-tagGroups: []

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

@ -91,6 +91,8 @@ do
menu="influxdb_$(echo $version | sed 's/\./_/g;s/v//g;')_ref"
if [[ $version == "cloud" ]]; then
titleVersion="Cloud"
elif [[ $version == "cloud-iox" ]]; then
titleVersion="Cloud (IOx)"
else
titleVersion="$version"
fi

17
api-docs/getswagger.sh
View File

@ -3,7 +3,7 @@
# This script provides a simple way grab the latest fully resolved openapi (OAS, OpenAPI Specification) contract files
# from the influxdata/openapi repo.
#
# Specify a platform to retrieve (cloud, oss, v1compat, all).
# Specify a platform to retrieve (cloud-iox, cloud, oss, v1compat, all).
# Optionally specify:
# - an OSS version as the second argument or using the -o flag.
# The version specifies where to write the updated openapi.
@ -20,6 +20,7 @@
# sh ./getswagger.sh -c <platform> -o <version> -b <baseUrl>
#
# Examples:
# sh ./getswagger.sh cloud-iox
# sh ./getswagger.sh cloud
# sh ./getswagger.sh -c oss -o v2.0 -b file:///Users/johnsmith/github/openapi
@ -56,7 +57,7 @@ function showHelp {
subcommand=$1
case "$subcommand" in
cloud|oss|v1compat|all)
cloud-iox|cloud|oss|v1compat|all)
platform=$1
shift
@ -131,6 +132,12 @@ function updateCloud {
postProcess $outFile cloud
}
function updateCloudIOx {
outFile="cloud-iox/ref.yml"
curl $UPDATE_OPTIONS ${baseUrl}/contracts/ref/cloud.yml -o $outFile
postProcess $outFile cloud-iox
}
function updateOSS {
mkdir -p ${ossVersion}
outFile="$ossVersion/ref.yml"
@ -160,6 +167,9 @@ fi
if [ "$platform" = "cloud" ];
then
updateCloud
elif [ "$platform" = "cloud-iox" ];
then
updateCloudIOx
elif [ "$platform" = "oss" ];
then
updateOSS
@ -169,9 +179,10 @@ then
elif [ "$platform" = "all" ];
then
updateCloud
updateCloudIOx
updateOSS
updateV1Compat
else
echo "Provide a platform argument: cloud, oss, v1compat, or all."
echo "Provide a platform argument: cloud, cloud-iox, oss, v1compat, or all."
showHelp
fi

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

@ -1,6 +1,6 @@
module.exports = SetTagGroups;
const { collect, getName, sortName } = require('../../helpers/content-helper.js')
const { collect, getName, sortName, isPresent } = require('../../helpers/content-helper.js')
/**
* Returns an object that defines handler functions for:
* - Operation nodes
@ -19,17 +19,47 @@ function SetTagGroups(data) {
data = [];
}
const ALL_ENDPOINTS = 'All endpoints';
/** Tag names used for ad-hoc grouping of Operations and not specific to a resource or path.
* For example, these might be useful for UI navigation and filtering, but shouldn't appear
* in a list of resource tags.
*/
const nonResourceTags = [
'Data I/O endpoints',
'Security and access endpoints',
'System information endpoints'
];
const allEndpointsGroup = data.filter(customGroup => customGroup.name === ALL_ENDPOINTS).pop();
let tags = [];
/** Collect tags for each operation and convert string tags to object tags. **/
return {
DefinitionRoot: {
Operation: {
leave(op) {
leave(op, ctx) {
let opTags = op.tags?.map(
function(t) {
return typeof t === 'string' ? { name: t } : t;
}
) || [];
const { parent, key } = ctx;
if(allEndpointsGroup) {
opTags.forEach(
function(t) {
if(!allEndpointsGroup.tags.includes(t.name) && !nonResourceTags.includes(t.name)) {
/** If a custom allEndpointsGroup is defined and the current Operation
* contains a tag not specified in allEndpointsGroup,
* then delete the Operation from the doc so that it doesn't appear in other tags.
*/
delete parent[key];
return;
}
}
)
}
tags = collect(tags, opTags);
}
},
@ -40,34 +70,24 @@ function SetTagGroups(data) {
endpointTags = root.tags
.filter(t => !t['x-traitTag'])
.filter(t => !nonResourceTags.includes(getName(t)))
.map(t => getName(t));
if(Array.isArray(root['x-tagGroups'])) {
root['x-tagGroups'].concat(data);
} else {
/** In Redoc, if x-tagGroups is present, a tag (and its paths)
* must be assigned to an x-tagGroup in order to display. */
if(data.length) {
addAllEndpointTags(data);
root['x-tagGroups'] = data;
}
let nonEndpointTags = []
root['x-tagGroups'].map(
function(grp) {
if(grp.name !== 'All endpoints') {
nonEndpointTags = nonEndpointTags.concat(grp.tags);
}
if(!['All endpoints', 'Overview'].includes(grp.name)) {
grp.name = ""
}
});
root['x-tagGroups'].map(
function(grp) {
if(grp.name === 'All endpoints') {
grp.tags = endpointTags
.filter(t => !nonEndpointTags.includes(t));
function addAllEndpointTags(tagGroups) {
tagGroups.map(grp => {
if(grp.name === 'All endpoints' && !grp.tags.length) {
grp.tags = endpointTags;
}
return grp;
}
)
})
}
}
}
}

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

@ -30,7 +30,7 @@ const decorators = {
'strip-trailing-slash': StripTrailingSlash,
'set-info': () => SetInfo(info()),
'set-tag-groups': () => SetTagGroups(tagGroups()),
'replace-docs-url-shortcode': ReplaceShortcodes().docsUrl,
'replace-docs-url-shortcode': ReplaceShortcodes().docsUrl
}
};
@ -50,7 +50,7 @@ module.exports = {
'docs/strip-trailing-slash': 'error',
'docs/set-info': 'error',
'docs/set-tag-groups': 'error',
'docs/replace-docs-url-shortcode': 'error',
'docs/replace-docs-url-shortcode': 'error'
},
},
},

13
api-docs/v2.6/content/tag-groups.yml Normal file
View File

@ -0,0 +1,13 @@
- name: Using the InfluxDB HTTP API
tags:
- Quick start
- Authentication
- Supported operations
- Headers
- Pagination
- Response codes
- Data I/O endpoints
- Security and access endpoints
- System information endpoints
- name: All endpoints
tags: []

13160
api-docs/v2.6/ref.yml
View File

File diff suppressed because it is too large Load Diff

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

@ -429,4 +429,3 @@ tags:
x-traitTag: true
- name: Query
- name: Write
x-tagGroups: []