From 22ec8b91e4d290a61c7fff8dea6dd76e54d2db14 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 1 Dec 2021 13:25:23 -0600 Subject: [PATCH] chore: update API docs to latest contract. Recombines /write for cloud and OSS. (#3451) --- api-docs/cloud/ref.yml | 59 +++++++++++++++++---------- api-docs/v2.1/ref.yml | 68 +++++++++++++++++++++++-------- api-docs/v2.1/swaggerV1Compat.yml | 4 +- 3 files changed, 91 insertions(+), 40 deletions(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index 3fac6d59b..00d799ea3 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -2395,11 +2395,6 @@ components: - invalid readOnly: true type: string - maxLength: - description: Max length in bytes for a body of line-protocol. - format: int32 - readOnly: true - type: integer message: description: Message is a human-readable message. readOnly: true @@ -2407,7 +2402,6 @@ components: required: - code - message - - maxLength Link: description: URI of resource. format: uri @@ -9989,7 +9983,7 @@ paths: description: Unexpected error summary: List scripts tags: - - Invokable Scripts + - Invocable Scripts post: operationId: PostScripts requestBody: @@ -10011,7 +10005,7 @@ paths: description: Unexpected error summary: Create a script tags: - - Invokable Scripts + - Invocable Scripts /api/v2/scripts/{scriptID}: delete: description: Deletes a script and all associated records. @@ -10031,9 +10025,9 @@ paths: description: Unexpected error summary: Delete a script tags: - - Invokable Scripts + - Invocable Scripts get: - description: Uses script ID to retrieve details of an invokable script. + description: Uses script ID to retrieve details of an invocable script. operationId: GetScriptsID parameters: - description: The script ID. @@ -10054,10 +10048,10 @@ paths: description: Unexpected error summary: Retrieve a script tags: - - Invokable Scripts + - Invocable Scripts patch: description: > - Updates properties (`name`, `description`, and `script`) of an invokable + Updates properties (`name`, `description`, and `script`) of an invocable script. operationId: PatchScriptsID parameters: @@ -10086,7 +10080,7 @@ paths: description: Unexpected error summary: Update a script tags: - - Invokable Scripts + - Invocable Scripts /api/v2/scripts/{scriptID}/invoke: post: description: >- @@ -10116,7 +10110,7 @@ paths: description: Unexpected error summary: Invoke a script tags: - - Invokable Scripts + - Invocable Scripts /api/v2/setup: get: description: >- @@ -12127,6 +12121,10 @@ paths: format. + InfluxDB Cloud enforces rate and size limits different from InfluxDB + OSS. For details, see Responses. + + For more information and examples, see the following: - [Write data with the InfluxDB @@ -12289,10 +12287,19 @@ paths: `bucket`, and name. '413': content: + application/json: + examples: + dataExceedsSizeLimitOSS: + summary: InfluxDB OSS response + value: > + {"code":"request too large","message":"unable to read data: + points batch is too large"} + schema: + $ref: '#/components/schemas/LineProtocolLengthError' text/html: examples: dataExceedsSizeLimit: - summary: Cloud response + summary: InfluxDB Cloud response value: | 413 Request Entity Too Large @@ -12304,13 +12311,21 @@ paths: schema: type: string - description: >- - Request entity too large. The payload exceeded the 50MB size limit. - 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. + + #### 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. '429': description: >- - The token is temporarily over quota. The Retry-After header - describes when to try the write again. + InfluxDB Cloud only. The token is temporarily over quota. The + Retry-After header describes when to try the write again. headers: Retry-After: description: >- @@ -12387,7 +12402,7 @@ tags: - DBRPs - Delete - DemoDataBuckets - - Invokable Scripts + - Invocable Scripts - Labels - Limits - NotificationEndpoints @@ -12519,7 +12534,7 @@ x-tagGroups: - DBRPs - Delete - DemoDataBuckets - - Invokable Scripts + - Invocable Scripts - Labels - Limits - NotificationEndpoints diff --git a/api-docs/v2.1/ref.yml b/api-docs/v2.1/ref.yml index 60ddded7c..fd6309f73 100644 --- a/api-docs/v2.1/ref.yml +++ b/api-docs/v2.1/ref.yml @@ -2294,11 +2294,6 @@ components: - invalid readOnly: true type: string - maxLength: - description: Max length in bytes for a body of line-protocol. - format: int32 - readOnly: true - type: integer message: description: Message is a human-readable message. readOnly: true @@ -2306,7 +2301,6 @@ components: required: - code - message - - maxLength Link: description: URI of resource. format: uri @@ -12717,7 +12711,8 @@ paths: To write data into InfluxDB, you need the following: - - **organization** – _See [View + + - **organization name or ID** – _See [View organizations](https://docs.influxdata.com/influxdb/v2.1/organizations/view-orgs/#view-your-organization-id) for instructions on viewing your organization ID._ @@ -12736,6 +12731,10 @@ paths: format. + InfluxDB Cloud enforces rate and size limits different from InfluxDB + OSS. For details, see Responses. + + For more information and examples, see the following: - [Write data with the InfluxDB @@ -12757,8 +12756,8 @@ paths: schema: default: identity description: >- - The header value specifies that the line protocol in the request - body is encoded with gzip or not encoded with identity. + The content coding. Use `gzip` for compressed data or `identity` + for unmodified, uncompressed data. enum: - gzip - identity @@ -12848,9 +12847,7 @@ paths: application/json: examples: measurementSchemaFieldTypeConflict: - summary: >- - Example of a field type conflict thrown by an explicit - bucket schema + summary: Field type conflict thrown by an explicit bucket schema value: code: invalid message: >- @@ -12901,13 +12898,52 @@ paths: '413': content: application/json: + examples: + dataExceedsSizeLimitOSS: + summary: InfluxDB OSS response + value: > + {"code":"request too large","message":"unable to read data: + points batch is too large"} schema: $ref: '#/components/schemas/LineProtocolLengthError' + text/html: + examples: + dataExceedsSizeLimit: + summary: InfluxDB Cloud response + value: | + + 413 Request Entity Too Large + +

413 Request Entity Too Large

+
+
nginx
+ + + schema: + type: string description: > - All request data was rejected and not written. InfluxDB OSS only - returns this error if the [Go (golang) - `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function - raises an error. + 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. + + #### 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. + '429': + description: >- + InfluxDB Cloud only. The 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: + format: int32 + type: integer '500': content: application/json: diff --git a/api-docs/v2.1/swaggerV1Compat.yml b/api-docs/v2.1/swaggerV1Compat.yml index 583c4b0d8..d0ab5fd9d 100644 --- a/api-docs/v2.1/swaggerV1Compat.yml +++ b/api-docs/v2.1/swaggerV1Compat.yml @@ -29,7 +29,7 @@ paths: schema: type: string required: true - description: The bucket to write to. If the specified bucket does not exist, a bucket is 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: @@ -54,7 +54,7 @@ paths: "204": description: Write data is correctly formatted and accepted for writing to the bucket. "400": - description: Line protocol was not in correct format, and no points were written. Response can be used to determine the first malformed line in the line-protocol body. All data in body was rejected and not written. + 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: