From 0e51239263fda088b60760c6c5730b48dd0af90c Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 12 May 2022 12:29:30 -0500 Subject: [PATCH] Fix API ref descriptions for `delete` and `write` (#4009) * fix: update /delete, /write, error refs, and misc. grammar. * chore: update name to @redocly/cli --- api-docs/cloud/ref.yml | 775 ++++++++++++++++++++++++++----------- api-docs/getswagger.sh | 2 +- api-docs/v2.2/ref.yml | 858 +++++++++++++++++++++++++++-------------- 3 files changed, 1124 insertions(+), 511 deletions(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index 76a133627..fcbc40394 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -51,6 +51,92 @@ components: schema: type: string responses: + AuthorizationError: + content: + application/json: + examples: + tokenNotAuthorized: + summary: Token is not authorized to access a resource + value: + code: unauthorized + message: unauthorized access + schema: + $ref: '#/components/schemas/Error' + description: | + Unauthorized. The error may indicate one of the following: + + * The `Authorization: Token` header is missing or malformed. + * The API token value is missing from the header. + * The token does not have sufficient permissions to write to this organization and bucket. + BadRequestError: + content: + application/json: + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if `org` or `orgID` does not match an organization. + GeneralServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Non 2XX error response from server. + InternalServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: | + Internal server error. + The server encountered an unexpected situation. + ResourceNotFoundError: + content: + application/json: + examples: + bucket-not-found: + summary: Bucket name not found + value: + code: not found + message: bucket "air_sensor" not found + org-not-found: + summary: Organization name not found + value: + code: not found + message: organization name "my-org" not found + orgID-not-found: + summary: Organization ID not found + value: + code: not found + message: organization not found + schema: + $ref: '#/components/schemas/Error' + description: > + Not found. + + A requested resource was not found. + + The response body contains the requested resource type and the name + value + + (if you passed it)--for example: + + + - `"organization name \"my-org\" not found"` + + - `"organization not found"`: indicates you passed an ID that did not + match + an organization. ServerError: content: application/json: @@ -1122,15 +1208,21 @@ components: description: The delete predicate request. properties: predicate: - description: InfluxQL-like delete statement + description: > + An expression in [delete predicate + syntax](https://docs.influxdata.com/influxdb/cloud/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string start: - description: RFC3339Nano + description: >- + A timestamp ([RFC3339 date/time + format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax)). format: date-time type: string stop: - description: RFC3339Nano + description: >- + A timestamp ([RFC3339 date/time + format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax)). format: date-time type: string required: @@ -4265,7 +4357,7 @@ components: properties: authorizationID: description: >- - ID of the authorization used when the task communicates with the + The ID of the authorization used when the task communicates with the query engine. type: string createdAt: @@ -4275,26 +4367,22 @@ components: cron: description: >- [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that - defines the schedule on which the task runs. Cron scheduling is - based on system time. - - Value is a [Cron - expression](https://en.wikipedia.org/wiki/Cron#Overview). + defines the schedule on which the task runs. InfluxDB bases cron + runs on the system time. type: string description: - description: Description of the task. + description: The description of the task. type: string every: description: >- - Interval at which the task runs. `every` also determines when the - task first runs, depending on the specified time. - - Value is a [duration - literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals)). + An interval ([duration + literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) + at which the task runs. `every` also determines when the task first + runs, depending on the specified time. format: duration type: string flux: - description: Flux script to run for this task. + description: The Flux script to run for this task. type: string id: readOnly: true @@ -4313,10 +4401,9 @@ components: type: string latestCompleted: description: >- - Timestamp of the latest scheduled and completed run. - - Value is a timestamp in [RFC3339 date/time - format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax). + A timestamp ([RFC3339 date/time + format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax)) + of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -4344,31 +4431,29 @@ components: readOnly: true type: object name: - description: Name of the task. + description: The name of the task. type: string offset: description: >- - [Duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) + A + [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. - - The value is a [duration - literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals). format: duration type: string org: - description: Name of the organization that owns the task. + description: The name of the organization that owns the task. type: string orgID: - description: ID of the organization that owns the task. + description: The ID of the organization that owns the task. type: string ownerID: - description: ID of the user who owns this Task. + description: The ID of the user who owns this Task. type: string status: $ref: '#/components/schemas/TaskStatusType' type: - description: Type of the task, useful for filtering a task list. + description: The type of the task, useful for filtering a task list. type: string updatedAt: format: date-time @@ -6009,7 +6094,7 @@ paths: $ref: '#/components/schemas/Authorizations' description: A list of authorizations default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: List all authorizations tags: @@ -6033,10 +6118,10 @@ paths: $ref: '#/components/schemas/Authorization' description: Authorization created '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Invalid request default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create an authorization tags: @@ -6056,7 +6141,7 @@ paths: '204': description: Authorization deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: @@ -6079,7 +6164,7 @@ paths: $ref: '#/components/schemas/Authorization' description: Authorization details default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: @@ -6110,7 +6195,7 @@ paths: $ref: '#/components/schemas/Authorization' description: The updated authorization. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Update authorization status tags: @@ -6591,7 +6676,7 @@ paths: schema: type: string '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Bucket not found summary: List all measurement schemas of a bucket tags: @@ -8080,66 +8165,200 @@ paths: - DBRPs /api/v2/delete: post: + description: > + Deletes data from a bucket. + + + Use this endpoint to delete points from a bucket in a specified time + range. + + + #### InfluxDB Cloud + + + - Does the following when you send a delete request: + + 1. Validates the request and queues the delete. + 2. Returns _success_ if queued; _error_ otherwise. + 3. Handles the delete asynchronously. + + #### InfluxDB OSS + + + - Validates the request, handles the delete synchronously, + and then responds with success or failure. + + #### Required permissions + + + - `write-buckets` or `write-bucket BUCKET_ID`. + + `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 + + + - [Delete + data](https://docs.influxdata.com/influxdb/cloud/write-data/delete-data/). + + - Learn how to use [delete predicate + syntax](https://docs.influxdata.com/influxdb/cloud/reference/syntax/delete-predicate/). + + - Learn how InfluxDB handles [deleted + tags](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/) + and [deleted fields](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). operationId: PostDelete parameters: - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the organization to delete data from. + - description: > + The organization to delete data from. + + If you pass both `orgID` and `org`, they must both be valid. + + + #### InfluxDB Cloud + + + - Doesn't require `org` or `orgID`. + + - Deletes data from the bucket in the organization associated with + the authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. in: query name: org schema: - description: Only points from this organization are deleted. + description: The organization name or ID. type: string - - description: Specifies the bucket to delete data from. + - description: > + The name or ID of the bucket to delete data from. + + If you pass both `bucket` and `bucketID`, `bucketID` takes + precedence. in: query name: bucket schema: - description: Only points from this bucket are deleted. + description: The bucket name or ID. type: string - - description: Specifies the organization ID of the resource. + - description: > + The ID of the organization to delete data from. + + If you pass both `orgID` and `org`, they must both be valid. + + + #### InfluxDB Cloud + + + - Doesn't require `org` or `orgID`. + + - Deletes data from the bucket in the organization associated with + the authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. in: query name: orgID schema: + description: The organization ID. type: string - - description: Specifies the bucket ID to delete data from. + - description: > + The ID of the bucket to delete data from. + + If you pass both `bucket` and `bucketID`, `bucketID` takes + precedence. in: query name: bucketID schema: - description: Only points from this bucket ID are deleted. + description: The bucket ID. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DeletePredicateRequest' - description: Deletes data from an InfluxDB bucket. + description: > + Time range parameters and an optional **delete predicate expression**. + + + To select points to delete within the specified time range, pass a + + **delete predicate expression** in the `predicate` property of the + request body. + + If you don't pass a `predicate`, InfluxDB deletes all data with + timestamps + + in the specified time range. + + + #### Related guides + + + - [Delete + data](https://docs.influxdata.com/influxdb/cloud/write-data/delete-data/). + + - Learn how to use [delete predicate + syntax](https://docs.influxdata.com/influxdb/cloud/reference/syntax/delete-predicate/). required: true responses: '204': - description: delete has been accepted + description: > + Success. + + + #### InfluxDB Cloud + + + - Validated and queued the request. + + - Handles the delete asynchronously - the deletion might not have + completed yet. + + + An HTTP `2xx` status code acknowledges that the write or delete is + queued. + + To ensure that InfluxDB Cloud handles writes and deletes in the + order you request them, + + wait for a response before you send the next request. + + + Because writes are asynchronous, data might not yet be written + + when you receive the response. + + + #### InfluxDB OSS + + + - Deleted the data. '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request. - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: no token was sent or does not have sufficient permissions. + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: the bucket or organization is not found. + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: internal server error + $ref: '#/components/responses/GeneralServerError' summary: Delete data tags: - Delete @@ -8180,13 +8399,11 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelsResponse' - description: A list of labels + description: Success. The response body contains a list of labels. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: List all labels tags: - Labels @@ -8197,7 +8414,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelCreateRequest' - description: Label to create + description: The label to create. required: true responses: '201': @@ -8205,13 +8422,11 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: Added label + description: Success. The label was created. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Create a label tags: - Labels @@ -8228,19 +8443,15 @@ paths: type: string responses: '204': - description: Delete has been accepted + description: Success. The delete was accepted. + '401': + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Label not found + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Delete a label tags: - Labels @@ -8260,13 +8471,11 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: A label + description: Success. The response body contains the label. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Retrieve a label tags: - Labels @@ -8285,7 +8494,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelUpdate' - description: Label update + description: A label update. required: true responses: '200': @@ -8293,19 +8502,15 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: Updated label + description: Success. The response body contains the updated label. + '401': + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Label not found + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Update a label tags: - Labels @@ -8337,13 +8542,13 @@ paths: application/json: schema: $ref: '#/components/schemas/UserResponse' - description: The currently authenticated user. + description: >- + Success. The response body contains the currently authenticated + user. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Retrieve the currently authenticated user tags: - Users @@ -8357,11 +8562,11 @@ paths: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' - description: New password + description: The new password. required: true responses: '204': - description: Password successfully updated + description: Success. The password was updated. default: content: application/json: @@ -9172,7 +9377,7 @@ paths: type: object description: Limits defined for the organization. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: unexpected error summary: Retrieve limits for an organization tags: @@ -9444,7 +9649,7 @@ paths: '204': description: Keys successfully deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete a secret from an organization tags: @@ -9550,7 +9755,7 @@ paths: - identity type: string default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: unexpected error summary: Retrieve usage for an organization tags: @@ -9601,32 +9806,36 @@ paths: /api/v2/query: post: description: > - Retrieves data from InfluxDB buckets. + Retrieves data from buckets. - To query data, you need the following: - - - **organization** – _See [View - organizations](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/#view-your-organization-id) - for instructions on viewing your organization 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/)_. - - - **Flux query** – _See [Flux](https://docs.influxdata.com/flux/v0.x/)._ + Use this endpoint to send a Flux query request and retreive data from a + bucket. - For more information and examples, see [Query with the InfluxDB + #### Rate limits (with InfluxDB Cloud) + + + `read` rate limits apply. + + For more information, see [limits and adjustable + quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). + + + #### Related guides + + + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/influx-api/). + + - [Get started with + Flux](https://docs.influxdata.com/flux/v0.x/get-started/) operationId: PostQuery parameters: - $ref: '#/components/parameters/TraceSpan' - description: >- - Indicates the content encoding (usually a compression algorithm) - that the client can understand. + The content encoding (usually a compression algorithm) that the + client can understand. in: header name: Accept-Encoding schema: @@ -9645,17 +9854,44 @@ paths: - application/json - application/vnd.flux type: string - - description: >- - Name of the organization executing the query. Accepts either the ID - or Name. If you provide both `orgID` and `org`, `org` takes - precedence. + - description: > + The name or ID of the organization executing the query. + + + #### InfluxDB Cloud + + + - Doesn't use `org` or `orgID`. + + - Queries the bucket in the organization associated with the + authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. in: query name: org schema: type: string - - description: >- - ID of the organization executing the query. If you provide both - `orgID` and `org`, `org` takes precedence. + - description: > + The ID of the organization executing the query. + + + #### InfluxDB Cloud + + + - Doesn't use `org` or `orgID`. + + - Queries the bucket in the organization associated with the + authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. in: query name: orgID schema: @@ -9684,26 +9920,32 @@ paths: mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 type: string - description: Success. Returns query results. + description: Success. The response body contains query results. headers: Content-Encoding: description: >- - Lists any encodings (usually compression algorithms) that have - been applied to the response payload. + Lists encodings (usually compression algorithms) that have been + applied to the response payload. schema: default: identity description: > - Content coding: `gzip` for compressed data or `identity` for - unmodified, uncompressed data. + The content coding: `gzip` for compressed data or `identity` + for unmodified, uncompressed data. enum: - gzip - identity type: string Trace-Id: - description: If generated, trace ID of the request. + description: The trace ID, if generated, of the request. schema: description: Trace ID of a request. type: string + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' '429': description: | #### InfluxDB Cloud: @@ -9723,12 +9965,10 @@ paths: schema: format: int32 type: integer + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Error processing query + $ref: '#/components/responses/GeneralServerError' summary: Query data tags: - Query @@ -10075,7 +10315,7 @@ paths: $ref: '#/components/schemas/OnboardingResponse' description: The created default user, bucket, and organization default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create an initial user, organization, and bucket tags: @@ -10101,7 +10341,7 @@ paths: $ref: '#/components/schemas/OnboardingResponse' description: The created default user, bucket, and organization. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create a new user, organization, and bucket tags: @@ -10426,6 +10666,22 @@ paths: maximum: 500 minimum: -1 type: integer + - description: The number of records to skip + in: query + name: offset + required: false + schema: + default: 0 + minimum: 0 + type: integer + - description: Field that records should be sorted by + in: query + name: sortBy + required: false + schema: + enum: + - name + type: string - description: Type of task, unset by default. in: query name: type @@ -11643,7 +11899,7 @@ paths: $ref: '#/components/schemas/Users' description: A list of users default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: List all users tags: @@ -11667,7 +11923,7 @@ paths: $ref: '#/components/schemas/UserResponse' description: User created default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create a user tags: @@ -11687,7 +11943,7 @@ paths: '204': description: User deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete a user tags: @@ -11710,7 +11966,7 @@ paths: $ref: '#/components/schemas/UserResponse' description: User details default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve a user tags: @@ -11740,7 +11996,7 @@ paths: $ref: '#/components/schemas/UserResponse' description: User updated default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Update a user tags: @@ -11800,10 +12056,10 @@ paths: $ref: '#/components/schemas/Variables' description: A list of variables for an organization. '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Invalid request default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: List all variables tags: @@ -11827,7 +12083,7 @@ paths: $ref: '#/components/schemas/Variable' description: Variable created default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Create a variable tags: @@ -11847,7 +12103,7 @@ paths: '204': description: Variable deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Delete a variable tags: @@ -11870,10 +12126,10 @@ paths: $ref: '#/components/schemas/Variable' description: Variable found '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Variable not found default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Retrieve a variable tags: @@ -11903,7 +12159,7 @@ paths: $ref: '#/components/schemas/Variable' description: Variable updated default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Update a variable tags: @@ -11933,7 +12189,7 @@ paths: $ref: '#/components/schemas/Variable' description: Variable updated default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Replace a variable tags: @@ -12043,20 +12299,37 @@ paths: 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. + #### InfluxDB Cloud + - Takes the following steps when you send a write request: + + 1. Validates the request and queues the write. + 2. If the write is queued, responds with an HTTP `204` status code. + 3. Handles the write asynchronously and reaches eventual consistency. + + An HTTP `2xx` status code acknowledges that the write or delete is queued. + To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, + wait for a response before you send the next request. + + Because writes are asynchronous, data might not yet be written + when you receive the response. + + #### InfluxDB OSS + + + - Validates the request, handles the write synchronously, + and then responds with success or failure. + - If all points were written successfully, returns `204`, + otherwise returns the first line that failed. + #### Required permissions - - `write-buckets` or `write-bucket BUCKET_ID` - - - `BUCKET_ID` is the ID of the destination bucket. + - `write-buckets` or `write-bucket BUCKET_ID`. + `BUCKET_ID` is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) @@ -12149,29 +12422,66 @@ paths: - description: > The destination organization for writes. - The database writes all points in the batch to this organization. + InfluxDB writes all points in the batch to this organization. - If you provide both `orgID` and `org` parameters, `org` takes - precedence. + If you pass both `orgID` and `org`, they must both be valid. + + + #### InfluxDB Cloud + + + - Doesn't require `org` or `orgID`. + + - Writes to the bucket in the organization associated with the + authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. + + - InfluxDB writes all points in the batch to this organization. in: query name: org required: true schema: description: The organization name or ID. type: string - - description: | + - description: > The ID of the destination organization for writes. - If both `orgID` and `org` are specified, `org` takes precedence. + + If you pass both `orgID` and `org`, they must both be valid. + + + #### InfluxDB Cloud + + + - Doesn't require `org` or `orgID`. + + - Writes to the bucket in the organization associated with the + authorization (API token). + + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. + + - InfluxDB writes all points in the batch to this organization. in: query name: orgID schema: type: string - - description: The destination bucket for writes. + - description: | + The destination bucket for writes. + InfluxDB writes all points in the batch to this bucket. in: query name: bucket required: true schema: - description: InfluxDB writes all points in the batch to this bucket. + description: The bucket name or ID. type: string - description: The precision for unix timestamps in the line protocol batch. in: query @@ -12213,12 +12523,22 @@ paths: responses: '204': description: > - Success. InfluxDB validated the request and the data format and + Success. - accepted the data for writing to the bucket. - Because data is written to InfluxDB asynchronously, data may not yet - be written to a bucket. + #### InfluxDB Cloud + + + - Validated and queued the request. + + - Handles the write asynchronously - the write might not have + completed yet. + + + #### InfluxDB OSS + + + - Successfully wrote all points in the batch. #### Related guides @@ -12245,42 +12565,14 @@ paths: schema: $ref: '#/components/schemas/LineProtocolError' description: | - Bad request. The line protocol data in the request is malformed. + 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: - application/json: - examples: - tokenNotAuthorized: - summary: >- - Token is not authorized to access the organization or - resource - value: - code: unauthorized - message: unauthorized access - schema: - $ref: '#/components/schemas/Error' - description: | - Unauthorized. The error may indicate one of the following: - * The `Authorization: Token` header is missing or malformed. - * The API token value is missing from the header. - * The token does not have sufficient permissions to write to this organization and bucket. + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - examples: - resource-not-found: - summary: Not found error - value: - code: not found - message: bucket "air_sensor" not found - schema: - $ref: '#/components/schemas/Error' - description: >- - Not found. A requested resource was not found. The response body - contains the requested resource type, e.g. `organization name` or - `bucket`, and name. + $ref: '#/components/responses/ResourceNotFoundError' '413': content: application/json: @@ -12344,16 +12636,7 @@ paths: format: int32 type: integer '500': - content: - application/json: - examples: - internalError: - summary: Internal error example - value: - code: internal error - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. + $ref: '#/components/responses/InternalServerError' '503': description: | Service unavailable. @@ -12378,7 +12661,7 @@ paths: format: int32 type: integer default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Write data tags: - Write @@ -12422,6 +12705,37 @@ tags: - name: Buckets - name: Cells - name: Checks + - description: > + Many InfluxDB API endpoints require parameters to specify resources--for + example, + + writing to a **bucket** in an **organization**. + + + ### Common query parameters + + + | Query parameter | Value type | + Description | + + |:------------------------ |:--------------------- + |:-------------------------------------------| + + | `bucket` | string | The bucket name or ID + ([find your bucket](/influxdb/cloud/organizations/buckets/view-buckets/). + | + + | `bucketID` | string | The bucket ID ([find + your bucket](/influxdb/cloud/organizations/buckets/view-buckets/). | + + | `org` | string | The organization name + or ID ([find your organization](/influxdb/cloud/organizations/view-orgs/). + | + + | `orgID` | 16-byte string | The organization ID + ([find your organization](/influxdb/cloud/organizations/view-orgs/). | + name: Common parameters + x-traitTag: true - name: Dashboards - name: DBRPs - name: Delete @@ -12589,6 +12903,7 @@ x-tagGroups: tags: - Write - Query + - Delete - Invokable Scripts - Tasks - name: Resource endpoints diff --git a/api-docs/getswagger.sh b/api-docs/getswagger.sh index eaa2d7560..925c83304 100755 --- a/api-docs/getswagger.sh +++ b/api-docs/getswagger.sh @@ -99,7 +99,7 @@ function postProcess() { version="$2" apiVersion="$3" - openapiCLI="@redocly/openapi-cli" + openapiCLI=" @redocly/cli" npx --version diff --git a/api-docs/v2.2/ref.yml b/api-docs/v2.2/ref.yml index 5c764c1b7..8b083ff60 100644 --- a/api-docs/v2.2/ref.yml +++ b/api-docs/v2.2/ref.yml @@ -51,6 +51,92 @@ components: schema: type: string responses: + AuthorizationError: + content: + application/json: + examples: + tokenNotAuthorized: + summary: Token is not authorized to access a resource + value: + code: unauthorized + message: unauthorized access + schema: + $ref: '#/components/schemas/Error' + description: | + Unauthorized. The error may indicate one of the following: + + * The `Authorization: Token` header is missing or malformed. + * The API token value is missing from the header. + * The token does not have sufficient permissions to write to this organization and bucket. + BadRequestError: + content: + application/json: + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if `org` or `orgID` does not match an organization. + GeneralServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Non 2XX error response from server. + InternalServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: | + Internal server error. + The server encountered an unexpected situation. + ResourceNotFoundError: + content: + application/json: + examples: + bucket-not-found: + summary: Bucket name not found + value: + code: not found + message: bucket "air_sensor" not found + org-not-found: + summary: Organization name not found + value: + code: not found + message: organization name "my-org" not found + orgID-not-found: + summary: Organization ID not found + value: + code: not found + message: organization not found + schema: + $ref: '#/components/schemas/Error' + description: > + Not found. + + A requested resource was not found. + + The response body contains the requested resource type and the name + value + + (if you passed it)--for example: + + + - `"organization name \"my-org\" not found"` + + - `"organization not found"`: indicates you passed an ID that did not + match + an organization. ServerError: content: application/json: @@ -1175,15 +1261,21 @@ components: description: The delete predicate request. properties: predicate: - description: InfluxQL-like delete statement + description: > + An expression in [delete predicate + syntax](https://docs.influxdata.com/influxdb/v2.2/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string start: - description: RFC3339Nano + description: >- + A timestamp ([RFC3339 date/time + format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax)). format: date-time type: string stop: - description: RFC3339Nano + description: >- + A timestamp ([RFC3339 date/time + format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax)). format: date-time type: string required: @@ -4429,7 +4521,7 @@ components: properties: authorizationID: description: >- - ID of the authorization used when the task communicates with the + The ID of the authorization used when the task communicates with the query engine. type: string createdAt: @@ -4439,26 +4531,22 @@ components: cron: description: >- [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that - defines the schedule on which the task runs. Cron scheduling is - based on system time. - - Value is a [Cron - expression](https://en.wikipedia.org/wiki/Cron#Overview). + defines the schedule on which the task runs. InfluxDB bases cron + runs on the system time. type: string description: - description: Description of the task. + description: The description of the task. type: string every: description: >- - Interval at which the task runs. `every` also determines when the - task first runs, depending on the specified time. - - Value is a [duration - literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals)). + An interval ([duration + literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) + at which the task runs. `every` also determines when the task first + runs, depending on the specified time. format: duration type: string flux: - description: Flux script to run for this task. + description: The Flux script to run for this task. type: string id: readOnly: true @@ -4477,10 +4565,9 @@ components: type: string latestCompleted: description: >- - Timestamp of the latest scheduled and completed run. - - Value is a timestamp in [RFC3339 date/time - format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax). + A timestamp ([RFC3339 date/time + format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax)) + of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -4508,31 +4595,29 @@ components: readOnly: true type: object name: - description: Name of the task. + description: The name of the task. type: string offset: description: >- - [Duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) + A + [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. - - The value is a [duration - literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals). format: duration type: string org: - description: Name of the organization that owns the task. + description: The name of the organization that owns the task. type: string orgID: - description: ID of the organization that owns the task. + description: The ID of the organization that owns the task. type: string ownerID: - description: ID of the user who owns this Task. + description: The ID of the user who owns this Task. type: string status: $ref: '#/components/schemas/TaskStatusType' type: - description: Type of the task, useful for filtering a task list. + description: The type of the task, useful for filtering a task list. type: string updatedAt: format: date-time @@ -6144,7 +6229,7 @@ paths: $ref: '#/components/schemas/Authorizations' description: A list of authorizations default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: List all authorizations tags: @@ -6168,10 +6253,10 @@ paths: $ref: '#/components/schemas/Authorization' description: Authorization created '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Invalid request default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create an authorization tags: @@ -6191,7 +6276,7 @@ paths: '204': description: Authorization deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: @@ -6214,7 +6299,7 @@ paths: $ref: '#/components/schemas/Authorization' description: Authorization details default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: @@ -6244,7 +6329,7 @@ paths: $ref: '#/components/schemas/Authorization' description: The active or inactive authorization default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Update an authorization to be active or inactive tags: @@ -6264,7 +6349,7 @@ paths: type: string description: Snapshot of KV metadata default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: >- Download snapshot of metadata stored in the server's embedded KV store. @@ -6313,7 +6398,7 @@ paths: - identity type: string default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Download snapshot of all metadata in the server tags: @@ -6379,7 +6464,7 @@ paths: $ref: '#/components/schemas/Error' description: Shard not found. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Download snapshot of all TSM data in a shard tags: @@ -7175,9 +7260,9 @@ paths: The response body contains the active runtime configuration of the InfluxDB instance. '401': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Retrieve runtime configuration tags: - Config @@ -8206,7 +8291,7 @@ paths: description: | [Go runtime profile](https://pkg.go.dev/runtime/pprof) reports. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve all runtime profiles @@ -8338,7 +8423,7 @@ paths: If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the memory allocations runtime profile @@ -8437,7 +8522,7 @@ paths: If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the block runtime profile @@ -8481,7 +8566,7 @@ paths: type: string description: Command line invocation. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the command line invocation @@ -8557,7 +8642,7 @@ paths: If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the goroutines runtime profile @@ -8675,7 +8760,7 @@ paths: If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the heap runtime profile @@ -8785,7 +8870,7 @@ paths: If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the mutual exclusion (mutex) runtime profile @@ -8849,7 +8934,7 @@ paths: with [pprof](https://github.com/google/pprof) analysis and visualization tools. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the CPU runtime profile @@ -8945,7 +9030,7 @@ paths: If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the threadcreate runtime profile @@ -9001,7 +9086,7 @@ paths: [Trace file](https://pkg.go.dev/runtime/trace) compatible with the [Golang `trace` command](https://pkg.go.dev/cmd/trace). default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the runtime execution trace @@ -9020,66 +9105,200 @@ paths: go tool trace ./trace /api/v2/delete: post: + description: > + Deletes data from a bucket. + + + Use this endpoint to delete points from a bucket in a specified time + range. + + + #### InfluxDB Cloud + + + - Does the following when you send a delete request: + + 1. Validates the request and queues the delete. + 2. Returns _success_ if queued; _error_ otherwise. + 3. Handles the delete asynchronously. + + #### InfluxDB OSS + + + - Validates the request, handles the delete synchronously, + and then responds with success or failure. + + #### Required permissions + + + - `write-buckets` or `write-bucket BUCKET_ID`. + + `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 + + + - [Delete + data](https://docs.influxdata.com/influxdb/v2.2/write-data/delete-data/). + + - Learn how to use [delete predicate + syntax](https://docs.influxdata.com/influxdb/v2.2/reference/syntax/delete-predicate/). + + - Learn how InfluxDB handles [deleted + tags](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/) + and [deleted fields](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). operationId: PostDelete parameters: - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the organization to delete data from. + - description: > + The organization to delete data from. + + If you pass both `orgID` and `org`, they must both be valid. + + + #### InfluxDB Cloud + + + - Doesn't require `org` or `orgID`. + + - Deletes data from the bucket in the organization associated with + the authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. in: query name: org schema: - description: Only points from this organization are deleted. + description: The organization name or ID. type: string - - description: Specifies the bucket to delete data from. + - description: > + The name or ID of the bucket to delete data from. + + If you pass both `bucket` and `bucketID`, `bucketID` takes + precedence. in: query name: bucket schema: - description: Only points from this bucket are deleted. + description: The bucket name or ID. type: string - - description: Specifies the organization ID of the resource. + - description: > + The ID of the organization to delete data from. + + If you pass both `orgID` and `org`, they must both be valid. + + + #### InfluxDB Cloud + + + - Doesn't require `org` or `orgID`. + + - Deletes data from the bucket in the organization associated with + the authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. in: query name: orgID schema: + description: The organization ID. type: string - - description: Specifies the bucket ID to delete data from. + - description: > + The ID of the bucket to delete data from. + + If you pass both `bucket` and `bucketID`, `bucketID` takes + precedence. in: query name: bucketID schema: - description: Only points from this bucket ID are deleted. + description: The bucket ID. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DeletePredicateRequest' - description: Deletes data from an InfluxDB bucket. + description: > + Time range parameters and an optional **delete predicate expression**. + + + To select points to delete within the specified time range, pass a + + **delete predicate expression** in the `predicate` property of the + request body. + + If you don't pass a `predicate`, InfluxDB deletes all data with + timestamps + + in the specified time range. + + + #### Related guides + + + - [Delete + data](https://docs.influxdata.com/influxdb/v2.2/write-data/delete-data/). + + - Learn how to use [delete predicate + syntax](https://docs.influxdata.com/influxdb/v2.2/reference/syntax/delete-predicate/). required: true responses: '204': - description: delete has been accepted + description: > + Success. + + + #### InfluxDB Cloud + + + - Validated and queued the request. + + - Handles the delete asynchronously - the deletion might not have + completed yet. + + + An HTTP `2xx` status code acknowledges that the write or delete is + queued. + + To ensure that InfluxDB Cloud handles writes and deletes in the + order you request them, + + wait for a response before you send the next request. + + + Because writes are asynchronous, data might not yet be written + + when you receive the response. + + + #### InfluxDB OSS + + + - Deleted the data. '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request. - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: no token was sent or does not have sufficient permissions. + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: the bucket or organization is not found. + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: internal server error + $ref: '#/components/responses/GeneralServerError' summary: Delete data tags: - Delete @@ -9126,7 +9345,7 @@ paths: $ref: '#/components/schemas/HealthCheck' description: The instance is unhealthy. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve the health of the instance @@ -9148,13 +9367,11 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelsResponse' - description: A list of labels + description: Success. The response body contains a list of labels. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: List all labels tags: - Labels @@ -9165,7 +9382,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelCreateRequest' - description: Label to create + description: The label to create. required: true responses: '201': @@ -9173,13 +9390,11 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: Added label + description: Success. The label was created. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Create a label tags: - Labels @@ -9196,19 +9411,15 @@ paths: type: string responses: '204': - description: Delete has been accepted + description: Success. The delete was accepted. + '401': + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Label not found + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Delete a label tags: - Labels @@ -9228,13 +9439,11 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: A label + description: Success. The response body contains the label. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Retrieve a label tags: - Labels @@ -9253,7 +9462,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelUpdate' - description: Label update + description: A label update. required: true responses: '200': @@ -9261,19 +9470,15 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: Updated label + description: Success. The response body contains the updated label. + '401': + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Label not found + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Update a label tags: - Labels @@ -9320,7 +9525,7 @@ paths: $ref: '#/components/schemas/Authorizations' description: A list of legacy authorizations default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: List all legacy authorizations tags: @@ -9344,10 +9549,10 @@ paths: $ref: '#/components/schemas/Authorization' description: Legacy authorization created '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Invalid request default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create a legacy authorization tags: @@ -9369,7 +9574,7 @@ paths: '204': description: Legacy authorization deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete a legacy authorization tags: @@ -9392,7 +9597,7 @@ paths: $ref: '#/components/schemas/Authorization' description: Legacy authorization details default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve a legacy authorization tags: @@ -9422,7 +9627,7 @@ paths: $ref: '#/components/schemas/Authorization' description: The active or inactive legacy authorization default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Update a legacy authorization to be active or inactive tags: @@ -9451,7 +9656,7 @@ paths: '204': description: Legacy authorization password set default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Set a legacy authorization password tags: @@ -9486,13 +9691,13 @@ paths: application/json: schema: $ref: '#/components/schemas/UserResponse' - description: The currently authenticated user. + description: >- + Success. The response body contains the currently authenticated + user. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Retrieve the currently authenticated user tags: - Users @@ -9506,11 +9711,11 @@ paths: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' - description: New password + description: The new password. required: true responses: '204': - description: Password successfully updated + description: Success. The password was updated. default: content: application/json: @@ -9597,7 +9802,7 @@ paths: type](https://prometheus.io/docs/concepts/metric_types/) (`counter`, `gauge`, `histogram`, or `summary`) default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Retrieve workload performance metrics @@ -10645,7 +10850,7 @@ paths: '204': description: Keys successfully deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete a secret from an organization tags: @@ -10727,32 +10932,36 @@ paths: /api/v2/query: post: description: > - Retrieves data from InfluxDB buckets. + Retrieves data from buckets. - To query data, you need the following: - - - **organization** – _See [View - organizations](https://docs.influxdata.com/influxdb/v2.2/organizations/view-orgs/#view-your-organization-id) - for instructions on viewing your organization ID._ - - - **API token** – _See [View - tokens](https://docs.influxdata.com/influxdb/v2.2/security/tokens/view-tokens/) - for instructions on viewing your API token._ - - **InfluxDB URL** – _See [InfluxDB - URLs](https://docs.influxdata.com/influxdb/v2.2/reference/urls/)_. - - - **Flux query** – _See [Flux](https://docs.influxdata.com/flux/v0.x/)._ + Use this endpoint to send a Flux query request and retreive data from a + bucket. - For more information and examples, see [Query with the InfluxDB + #### Rate limits (with InfluxDB Cloud) + + + `read` rate limits apply. + + For more information, see [limits and adjustable + quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). + + + #### Related guides + + + - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/v2.2/query-data/execute-queries/influx-api/). + + - [Get started with + Flux](https://docs.influxdata.com/flux/v0.x/get-started/) operationId: PostQuery parameters: - $ref: '#/components/parameters/TraceSpan' - description: >- - Indicates the content encoding (usually a compression algorithm) - that the client can understand. + The content encoding (usually a compression algorithm) that the + client can understand. in: header name: Accept-Encoding schema: @@ -10771,17 +10980,44 @@ paths: - application/json - application/vnd.flux type: string - - description: >- - Name of the organization executing the query. Accepts either the ID - or Name. If you provide both `orgID` and `org`, `org` takes - precedence. + - description: > + The name or ID of the organization executing the query. + + + #### InfluxDB Cloud + + + - Doesn't use `org` or `orgID`. + + - Queries the bucket in the organization associated with the + authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. in: query name: org schema: type: string - - description: >- - ID of the organization executing the query. If you provide both - `orgID` and `org`, `org` takes precedence. + - description: > + The ID of the organization executing the query. + + + #### InfluxDB Cloud + + + - Doesn't use `org` or `orgID`. + + - Queries the bucket in the organization associated with the + authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. in: query name: orgID schema: @@ -10810,26 +11046,32 @@ paths: mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 type: string - description: Success. Returns query results. + description: Success. The response body contains query results. headers: Content-Encoding: description: >- - Lists any encodings (usually compression algorithms) that have - been applied to the response payload. + Lists encodings (usually compression algorithms) that have been + applied to the response payload. schema: default: identity description: > - Content coding: `gzip` for compressed data or `identity` for - unmodified, uncompressed data. + The content coding: `gzip` for compressed data or `identity` + for unmodified, uncompressed data. enum: - gzip - identity type: string Trace-Id: - description: If generated, trace ID of the request. + description: The trace ID, if generated, of the request. schema: description: Trace ID of a request. type: string + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' '429': description: | #### InfluxDB Cloud: @@ -10849,12 +11091,10 @@ paths: schema: format: int32 type: integer + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Error processing query + $ref: '#/components/responses/GeneralServerError' summary: Query data tags: - Query @@ -10995,7 +11235,7 @@ paths: $ref: '#/components/schemas/Ready' description: The instance is ready default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error servers: [] summary: Get the readiness of an instance at startup @@ -11029,9 +11269,9 @@ paths: $ref: '#/components/schemas/RemoteConnections' description: List of remote connections '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: List all remote connections tags: - RemoteConnections @@ -11051,9 +11291,9 @@ paths: $ref: '#/components/schemas/RemoteConnection' description: Remote connection saved '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Register a new remote connection tags: - RemoteConnections @@ -11071,9 +11311,9 @@ paths: '204': description: Remote connection info deleted. '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Delete a remote connection tags: - RemoteConnections @@ -11094,9 +11334,9 @@ paths: $ref: '#/components/schemas/RemoteConnection' description: Remote connection '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Retrieve a remote connection tags: - RemoteConnections @@ -11123,11 +11363,11 @@ paths: $ref: '#/components/schemas/RemoteConnection' description: Updated information saved '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Update a remote connection tags: - RemoteConnections @@ -11162,9 +11402,9 @@ paths: $ref: '#/components/schemas/Replications' description: List of replications '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: List all replications tags: - Replications @@ -11194,9 +11434,9 @@ paths: '204': description: Replication validated, but not saved '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Register a new replication tags: - Replications @@ -11214,9 +11454,9 @@ paths: '204': description: Replication deleted. '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Delete a replication tags: - Replications @@ -11237,9 +11477,9 @@ paths: $ref: '#/components/schemas/Replication' description: Replication '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Retrieve a replication tags: - Replications @@ -11274,11 +11514,11 @@ paths: '204': description: Updated replication validated, but not saved '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Update a replication tags: - Replications @@ -11296,10 +11536,10 @@ paths: '204': description: Replication is valid '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Replication failed validation default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Validate a replication tags: - Replications @@ -11362,7 +11602,7 @@ paths: type: string description: ID mappings for shards in bucket. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Overwrite storage metadata for a bucket with shard info from a backup. tags: @@ -11387,7 +11627,7 @@ paths: $ref: '#/components/schemas/RestoredBucketMappings' description: ID mappings for shards in new bucket. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create a new bucket pre-seeded with shard info from a backup. tags: @@ -11445,7 +11685,7 @@ paths: '204': description: KV store successfully overwritten. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Overwrite the embedded KV store on the server with a backed-up snapshot. tags: @@ -11497,7 +11737,7 @@ paths: '204': description: TSM snapshot successfully restored. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Restore a TSM snapshot into a shard. tags: @@ -11543,7 +11783,7 @@ paths: '204': description: SQL store successfully overwritten. default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: >- Overwrite the embedded SQL store on the server with a backed-up @@ -12009,7 +12249,7 @@ paths: $ref: '#/components/schemas/OnboardingResponse' description: Created default user, bucket, org default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Set up initial user, org and bucket tags: @@ -13771,7 +14011,7 @@ paths: $ref: '#/components/schemas/Users' description: A list of users default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: List all users tags: @@ -13795,7 +14035,7 @@ paths: $ref: '#/components/schemas/UserResponse' description: User created default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Create a user tags: @@ -13815,7 +14055,7 @@ paths: '204': description: User deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete a user tags: @@ -13838,7 +14078,7 @@ paths: $ref: '#/components/schemas/UserResponse' description: User details default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve a user tags: @@ -13868,7 +14108,7 @@ paths: $ref: '#/components/schemas/UserResponse' description: User updated default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Update a user tags: @@ -13928,10 +14168,10 @@ paths: $ref: '#/components/schemas/Variables' description: A list of variables for an organization '400': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Invalid request default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: List all variables tags: @@ -13955,7 +14195,7 @@ paths: $ref: '#/components/schemas/Variable' description: Variable created default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Create a variable tags: @@ -13975,7 +14215,7 @@ paths: '204': description: Variable deleted default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Delete a variable tags: @@ -13998,10 +14238,10 @@ paths: $ref: '#/components/schemas/Variable' description: Variable found '404': - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Variable not found default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Retrieve a variable tags: @@ -14031,7 +14271,7 @@ paths: $ref: '#/components/schemas/Variable' description: Variable updated default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Update a variable tags: @@ -14061,7 +14301,7 @@ paths: $ref: '#/components/schemas/Variable' description: Variable updated default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' description: Internal server error summary: Replace a variable tags: @@ -14171,20 +14411,37 @@ paths: protocol](https://docs.influxdata.com/influxdb/v2.2/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. + #### InfluxDB Cloud + - Takes the following steps when you send a write request: + + 1. Validates the request and queues the write. + 2. If the write is queued, responds with an HTTP `204` status code. + 3. Handles the write asynchronously and reaches eventual consistency. + + An HTTP `2xx` status code acknowledges that the write or delete is queued. + To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, + wait for a response before you send the next request. + + Because writes are asynchronous, data might not yet be written + when you receive the response. + + #### InfluxDB OSS + + + - Validates the request, handles the write synchronously, + and then responds with success or failure. + - If all points were written successfully, returns `204`, + otherwise returns the first line that failed. + #### Required permissions - - `write-buckets` or `write-bucket BUCKET_ID` - - - `BUCKET_ID` is the ID of the destination bucket. + - `write-buckets` or `write-bucket BUCKET_ID`. + `BUCKET_ID` is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) @@ -14277,29 +14534,66 @@ paths: - description: > The destination organization for writes. - The database writes all points in the batch to this organization. + InfluxDB writes all points in the batch to this organization. - If you provide both `orgID` and `org` parameters, `org` takes - precedence. + If you pass both `orgID` and `org`, they must both be valid. + + + #### InfluxDB Cloud + + + - Doesn't require `org` or `orgID`. + + - Writes to the bucket in the organization associated with the + authorization (API token). + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. + + - InfluxDB writes all points in the batch to this organization. in: query name: org required: true schema: description: The organization name or ID. type: string - - description: | + - description: > The ID of the destination organization for writes. - If both `orgID` and `org` are specified, `org` takes precedence. + + If you pass both `orgID` and `org`, they must both be valid. + + + #### InfluxDB Cloud + + + - Doesn't require `org` or `orgID`. + + - Writes to the bucket in the organization associated with the + authorization (API token). + + + + #### InfluxDB OSS + + + - Requires either `org` or `orgID`. + + - InfluxDB writes all points in the batch to this organization. in: query name: orgID schema: type: string - - description: The destination bucket for writes. + - description: | + The destination bucket for writes. + InfluxDB writes all points in the batch to this bucket. in: query name: bucket required: true schema: - description: InfluxDB writes all points in the batch to this bucket. + description: The bucket name or ID. type: string - description: The precision for unix timestamps in the line protocol batch. in: query @@ -14341,12 +14635,22 @@ paths: responses: '204': description: > - Success. InfluxDB validated the request and the data format and + Success. - accepted the data for writing to the bucket. - Because data is written to InfluxDB asynchronously, data may not yet - be written to a bucket. + #### InfluxDB Cloud + + + - Validated and queued the request. + + - Handles the write asynchronously - the write might not have + completed yet. + + + #### InfluxDB OSS + + + - Successfully wrote all points in the batch. #### Related guides @@ -14373,42 +14677,14 @@ paths: schema: $ref: '#/components/schemas/LineProtocolError' description: | - Bad request. The line protocol data in the request is malformed. + 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: - application/json: - examples: - tokenNotAuthorized: - summary: >- - Token is not authorized to access the organization or - resource - value: - code: unauthorized - message: unauthorized access - schema: - $ref: '#/components/schemas/Error' - description: | - Unauthorized. The error may indicate one of the following: - * The `Authorization: Token` header is missing or malformed. - * The API token value is missing from the header. - * The token does not have sufficient permissions to write to this organization and bucket. + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - examples: - resource-not-found: - summary: Not found error - value: - code: not found - message: bucket "air_sensor" not found - schema: - $ref: '#/components/schemas/Error' - description: >- - Not found. A requested resource was not found. The response body - contains the requested resource type, e.g. `organization name` or - `bucket`, and name. + $ref: '#/components/responses/ResourceNotFoundError' '413': content: application/json: @@ -14472,16 +14748,7 @@ paths: format: int32 type: integer '500': - content: - application/json: - examples: - internalError: - summary: Internal error example - value: - code: internal error - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. + $ref: '#/components/responses/InternalServerError' '503': description: | Service unavailable. @@ -14506,7 +14773,7 @@ paths: format: int32 type: integer default: - $ref: '#/components/responses/ServerError' + $ref: '#/components/responses/GeneralServerError' summary: Write data tags: - Write @@ -14550,6 +14817,36 @@ tags: - name: Buckets - name: Cells - name: Checks + - description: > + Many InfluxDB API endpoints require parameters to specify resources--for + example, + + writing to a **bucket** in an **organization**. + + + ### Common query parameters + + + | Query parameter | Value type | + Description | + + |:------------------------ |:--------------------- + |:-------------------------------------------| + + | `bucket` | string | The bucket name or ID + ([find your bucket](/influxdb/v2.2/organizations/buckets/view-buckets/). | + + | `bucketID` | string | The bucket ID ([find + your bucket](/influxdb/v2.2/organizations/buckets/view-buckets/). | + + | `org` | string | The organization name + or ID ([find your organization](/influxdb/v2.2/organizations/view-orgs/). + | + + | `orgID` | 16-byte string | The organization ID + ([find your organization](/influxdb/v2.2/organizations/view-orgs/). | + name: Common parameters + x-traitTag: true - name: Config - name: Dashboards - name: DBRPs @@ -14723,6 +15020,7 @@ x-tagGroups: tags: - Write - Query + - Delete - Tasks - name: Resource endpoints tags: