pathTemplate.yml

openapi: '3.0.2'
info:
  title: InfluxData OpenAPI 3.x Path template
  description: | 
    This OpenAPI specification provides a template for OpenAPI 3.x Path elements
    in influxdata/openapi.
    The template provides guidelines for 
    `summary`, `description`, and `response` elements in OpenAPI Paths and Operations.

    # Usage
    
    The template in the `x-influxdataPathTemplate` vendor extension element defines a 
    valid OpenAPI Path object that provides guidelines and examples for 
    InfluxDB API endpoints.

    You can use common OpenAPI tooling (e.g. OpenAPI Preview and Redocly OpenAPI)
    to preview and validate this spec.
    
    ## How to use template guidelines
   
    - Follow guidelines provided in Bash-style comments (`#`) that precede
      OpenAPI elements.
    - Follow [Google styles for API methods](https://developers.google.com/style/api-reference-comments#methods).
    
    ## How to use template examples

    - Fields that support Markdown (`description` and `value`)
      contain examples in HTML comments (`<!--- --->`).

      To use examples, do the following:

        - Copy-paste examples into your spec and edit them as needed.
        - Remove comment tags before generating contracts.
        - Keep in mind, HTML comments might be preserved in downstream contracts
          and HTML even if they're not rendered.

    ## description fields

    When writing `description` fields, do the following:

      - Use [CommonMark syntax](https://spec.commonmark.org/0.30/).
      - Include the template section headings (in Markdown `####` level 4 tags).
      - Follow guidelines (`#` comments) and examples (`<!--- --->`` HTML comments).
      - In links to InfluxData documentation, use the 
        `{{% INFLUXDB_DOCS_URL %}}` variable to replace the domain and
        platform-specific path in URLs, for example:

        - `[Authentication]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)`. 

    For path and operation (method) descriptions:
      - Start with an active verb that describes what the operation does.
      - See https://cloud.google.com/apis/design/documentation#api_description
        for more examples.

    For parameter (path, query, header) descriptions:
      - Use a noun phrase that describes the field or parameter.
      - See https://cloud.google.com/apis/design/documentation#field_and_parameter_descriptions
        for more examples.
    
    This template isn't meant to be exhaustive--the complete set of
    child elements in your spec depends on the Operation.
    For example, each Operation (`get`, `put`, etc) should define
    response codes with descriptions and examples specific for the Operation.

  version: '1.0'
  license:
    name: MIT
    url: 'https://opensource.org/licenses/MIT'
servers:
  - url: '' 
paths:
  /tasks:
    $ref: '#/x-influxdataPathTemplate'
x-influxdataPathTemplate:

  # Path description
  # 
  # 1. In the first sentence, start with a verb and use present tense to briefly 
  #    state what action the method performs.
  # 
  # 2. Provide the following context:
  #  - Why a developer would use this path.
  #  - Relationships to important resources or concepts, especially if they're
  #    not obvious.
  description: |
    <!--- Example: Path description for `/authorizations`
     
    Creates and manages API tokens for access to InfluxDB resources.

    An **authorization** associates a list of permissions to an **organization**
    and provides a token for API access.
    You can restrict an authorization and its token to a specific user.

    #### Related guides

      - [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication).
      - [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/).
      - [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).

    --->

  # Path parameters
  # 
  # - List Parameter objects that apply to *all* operations in this path.
  parameters: []
  
  post:

    # operationId
    # Used in links.
    #
    # Use the convention OperationPathname.
    operationId: PostTasks

    # Operation tags
    # Used for grouping and menus.
    #
    # Include the Pathname.
    # To learn how tags are used, see the [README](../../README.md)
    tags:
      - Tasks

    # Operation summary
    # Used in section headings and nav menus.
    #
    # For the Operation summary, state the 
    # developer's action, starting with the base form of the verb
    # (Add, Create, Delete, List, Update, Retrieve)--for example:
    #
    # - Add an owner to a bucket
    # - Create a bucket
    # 
    # For more guidance, see https://developers.google.com/style/headings?hl=en#heading-and-title-text
    summary: Create a task

    # Operation description
    #
    # 1. In the first sentence, start with a verb
    #   (Adds, Creates, Deletes, Lists, Updates, Returns)
    #    and briefly state in present tense what action the operation performs
    #    --for example:
    #
    #    - Returns a task.
    #    - Adds a new bucket to the organization and returns the bucket.   
    #    - Updates the authorization status and returns the active or inactive
    #      authorization.
    #
    #    For more help, see https://developers.google.com/style/api-reference-comments?hl=en#description.
    #
    # 2. For deprecated operations, set the `deprecated` Operation field to
    #    `true` and add a link here to the new operation--for example:
    #
    #    - **Deprecated**.
    #      Use [`PATCH /api/v2/tasks/{taskID}`](#operation/PatchTasksID) instead.
    # 
    # 3. Describe the following:
    #   - Why and when to use this Operation
    #   - Idempotency
    #   - Side effects
    #   - Requirements that are "hidden" or not obvious from the requestBody or
    #   - parameter definitions
    #   - Assumptions data sources, formats, I/O, or the state of a resource
    #   - Nuances in requests, response codes, or payloads.
    #
    # 4. Describe unique relationships to other InfluxDB resources or concepts,
    #    especially if they're not obvious--for example:

    #    - Use `POST /api/v2/authorizations` to create InfluxDB API tokens.
    # 
    # #### Required permissions
    #
    # - List permissions required for the operation.
    #
    # #### Rate limits (with InfluxDB Cloud)
    #   
    # For Rate limits, include a link to rate limits documentation for
    # InfluxDB Cloud.
    # If an endpoint introduces a change to limits or quotas, create a PR or 
    # issue at https://github.com/influxdata/docs-v2/.
    # 
    # #### Related guides
    # 
    # For Related guides, include links to documented procedures and tutorials.
    description: |
      <!--- Example: Operation description for `POST /task`

      Creates a task and returns the new task.

      Use this endpoint to schedule a [Flux script](https://docs.influxdata.com/flux/v0.x/) that takes a stream of 
      input data, modifies or analyzes it, and then writes the modified data
      to a bucket or performs some action.

      #### Required permissions

      - `write-tasks`
      - 'read-buckets'
      - `write-buckets` or `write-bucket BUCKET_ID`
      
      `BUCKET_ID` is the ID of the destination bucket.

      #### Limitations
      
      #### Rate limits (with InfluxDB Cloud)

      `write` rate limits apply.
      For more information, see [limits and adjustable quotas]({{% INFLUXDB_DOCS_URL %}}/influxdb/cloud/account-management/limits/).
      
      #### Related guides

      - [Create a task]({{% INFLUXDB_DOCS_URL %}}/manage-tasks/create-task/).
      - [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/).

      --->

    requestBody:
      
      # Request Body description
      #
      # 1. In the first line, briefly state what the body represents.
      #
      # 2. Describe options and encodings for sending the request payload.
      #
      # 3. If a header or query parameter influences handling of the body,
      #    describe the parameter and its effect.
      #
      # 4. List default values.
      description: | 
        <!--- Example: Request Body description for `PATCH /tasks/{taskID}` 

        Task with updates to apply

        --->
       
        <!--- Example: Request Body description for `POST /write`

        Data in line protocol format

        To send compressed data, do the following:
          
          1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data.
          2. In your request, send the compressed data and the 
             `Content-Encoding: gzip` header.     
        
        #### Related guides
        
        - [Best practices for optimizing writes]({{% INFLUXDB_DOCS_URL%}}/write-data/best-practices/optimize-writes/).

        --->

      content:

        # Request Body Media Type
        #
        # If the schema can't generate an example (e.g. for a non-JSON body),
        # provide one.
        text/plain:
          schema:
            type: string
            format: byte
            description: |
              <!--- Example: line protocol schema

              Line protocol

              --->
          examples:
            line-protocol:
              summary: Line protocol
              description: Data in line protocol format.
              value: |
                airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000
                airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000

    # Parameters
    #
    # - Include request headers that are required for the operation.

    # - Include request headers that use specific or unique values for the operation.

    # - Include all HTTP request parameters.
    parameters:
      - in: header
        name: Content-Type

        # Header parameter description
        # 
        # If a value is required, how does it affect the following:
        #  
        #  1. handling of the request payload?
        # 
        #  2. the response?
        description: |
          <!--- Example --->

        schema:
          type: string
          default: text/plain; charset=utf-8
          enum:
            - text/plain
            - text/plain; charset=utf-8

        # Header parameter examples
        #
        # 1. For the `summary`, provide a short name for the value.
        #
        # 2. Describe the effect on, or relationship, to the request body.
        #
        # 3. Provide an example with the header name and value.
        examples:
          default:
            summary: Default content type for line protocol
            description: |
              <!--- Example: Line protocol default content type
              `text/plain` is the content type for line protocol.
              `UTF-8` is the default character set for line protocol.
              --->
            value: {"Content-Type": "text/plain; charset=utf-8"}
          text-plain:
            summary: Plain text, unspecified character set
            value: {"Content-Type": "text/plain"}
      - in: query
        name: org

        # Query parameter description
        #
        # 1. Describe how to find the value. Provide a link to additional
        #    documentation.
        #
        # 2. Explain precedence or exclusivity when combined with other parameters.
        description: |
          <!--- Example: `org` parameter description

          Organization that contains the bucket you want to write to.
          InfluxDB writes all points in the batch to this organization. 
          
          If you provide both `orgID` and `org`, `org` takes precedence.

          To find your organization, see how to 
          [view organizations]({{% INFLUXDB_DOCS_URL %}}/organizations/view-orgs/).
          --->

          <!--- Example: bucketID parameter description

          To find the bucket ID, use the [`buckets`]() endpoint.
          If you provide both `bucketId` and `bucket`, `bucketId` takes precedence.

          --->
        required: true
        schema:
          type: string
          description: Organization name or ID.
    responses:
      '200':

        # 2xx Response description
        #
        # 1. For the first sentence, state "Success."
        #
        # 2. If it returns a body, briefly state what the response body contains.
        #
        # 3. For asynchronous operations, explain the following:
        #    - What part was successful and what part is asynchronous
        #    - How to check that the operation completed
        #    - How to troubleshoot problems
        description: |
          <!--- Example description for `PATCH /authorization` 200 response status

          Success. The response body contains the updated active or inactive 
          authorization.

          --->

        # Response content
        #
        # If the response contains a (payload) body, provide the content field
        # with a 
        # [Media Type](https://swagger.io/docs/specification/media-types/).
        # In the Media Type, include the response body schema and an example.
        content:
          text/csv:
            schema:
              type: string

              # Response example
              #
              # If the schema can't generate an example
              # (e.g. for a non-JSON body), provide one.
              example: >
                <!--- Example: CSV body for `POST /query` 200 response status

                result,table,_start,_stop,_time,region,host,_value
                mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
                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

                --->
      
      "204":
        description: |
          <!--- Example: 204 Response description for asynchronous `POST /write`
            
          InfluxDB validated the request data format and accepted the data for
          writing to the bucket.
          Because data is written to InfluxDB asynchronously,
          data may not yet be written to a bucket.

          #### Error handling

          - If some of your data didn’t write to the bucket,
            see [how to check for write errors]({{% INFLUXDB_DOCS_URL %}}/write-data/troubleshoot/).
          
          --->
        
        # 204 Response content
        #
        # If the response contains a payload (a 204 response shouldn't),
        # provide the content field with a [Media Type](https://swagger.io/docs/specification/media-types/)
        # that contains the response schema and an example.
        content:
          text/csv:
            schema:
              type: string
              example: >
                <!--- Example: Response content

                Success

                --->

      "400":
        
        # 4xx Response description
        #
        # 1. In the first sentence, provide the response status text.
        #
        # 2. Describe the following:
        #    - cause of the error
        #    - what the response payload contains - if platforms diverge, 
        #       include platform headings--for example:
        #      - **InfluxDB Cloud**
        #      - **InfluxDB OSS**
        #    - outcome of the error
        #
        # #### Error handling
        #
        # Link to error handling or troubleshooting documentation not included
        # in the Operation description.
        description: |
          <!--- Example: 400 description for `POST /write`

          Bad request.
          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.
          
          #### Error handling

          - [Troubleshoot issues writing data]({{% INFLUXDB_DOCS_URL %}}/write-data/troubleshoot/)
       
          --->
        content:
          application/json:
            schema:
              $ref: "../../src/common/schemas/LineProtocolError.yml"
            examples:
              measurementSchemaFieldTypeConflict:
                summary: InfluxDB Cloud field type conflict thrown by an explicit bucket schema
                value: {
                  "code": "invalid",
                  "message": "partial write error (2 written): unable to parse 'air_sensor,service=S1,sensor=L1 temperature=\"90.5\",humidity=70.0 1632850122': schema: field type for field \"temperature\" not permitted by schema; got String but expected Float",
                  "op": "",
                  "err": ""
                  }
      "401":
        $ref: "../../src/common/responses/AuthorizationError.yml"
      "404":
        $ref: "../../src/common/responses/ResourceNotFoundError.yml"

      "413":
        description: |
          <!--- Example: 413 description with platform divergence for `POST /write`

          The request payload is too large.
          InfluxDB rejected the batch and did not write any data.

          #### InfluxDB Cloud:

            - returns this error if the request exceeds the maximum 
              [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits).
            - 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.
          
          #### Error handling

            - [Troubleshoot issues writing data]({{% INFLUXDB_DOCS_URL %}}/write-data/troubleshoot/)

          --->
            
        # 4xx Response content
        #
        # Provide a response example.
        # If platforms (OSS and Cloud) differ in their responses, provide 
        # examples with the following fields:
        #
        # - summary with "InfluxDB OSS response" or "InfluxDB Cloud response"
        # - value with the response body
        content:
          # application/json must be listed first for the influx-cli codegen 
          # to work properly, see https://github.com/influxdata/openapi/pull/253
          application/json:
            schema:
              $ref: "../../src/common/schemas/LineProtocolLengthError.yml"
            examples:
              dataExceedsSizeLimitOSS:
                summary: InfluxDB OSS response
                value: |
                  <!--- Example: 413 Response example value for OSS `POST /write`
                  
                  {"code":"request too large","message":"unable to read data: points batch is too large"}

                  --->
          text/html:
            schema:
              type: string
            examples:
              dataExceedsSizeLimit:
                summary: InfluxDB Cloud response
                value: |
                  <!--- Example: 413 Response example value for Cloud `POST /write`

                  <html>
                    <head><title>413 Request Entity Too Large</title></head>
                    <body>
                      <center><h1>413 Request Entity Too Large</h1></center>
                      <hr>
                      <center>nginx</center>
                    </body>
                  </html>

                  --->
      "429":
        description: >
          <!--- Example: 429 Response description

          #### InfluxDB Cloud

            - Returns this error if a **read** or **write** request exceeds your
              plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas)
              or if a **delete** request exceeds the maximum
              [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits).
            - Returns `Retry-After` header that describes when to try the write
              again.

          #### InfluxDB OSS

            - Doesn't return this error.

          --->
        headers:
          Retry-After:
            description: |
              <!--- Example: Response `Retry-After` header description

                Non-negative decimal integer indicating seconds to wait before
                retrying the request.

              --->
            schema:
              type: integer
              format: int32
      "500":
        $ref: "../../src/common/responses/InternalServerError.yml"
      "503":
        description: >
          <!--- Example: 503 Response description with platform divergence

          **InfluxDB Cloud** returns the following:

            - `503` if series cardinality exceeds your plan's
              [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas).
              See [how to resolve high series cardinality]({{% INFLUXDB_DOCS_URL %}}/write-data/best-practices/resolve-high-cardinality/).
  
          **InfluxDB OSS** returns the following:
  
            - `503` if the server is temporarily unavailable to accept writes.
            - `Retry-After` header that describes when to try the write again.

          --->
        headers:
          Retry-After:
            description: |
              <!--- Example: Response `Retry-After` header description

              Non-negative decimal integer indicating seconds to wait before 
              retrying the request.

              --->
            schema:
              type: integer
              format: int32
    # Code samples
    # 
    # Provide at least one minimal code sample for API reference docs users.
    # 
    # - Include the `x-codeSamples` element in the Path.
    #   `x-codeSamples` is a vendor extension element that takes a list of samples.
    # 
    # - For the InfluxDB base URL, use the OSS default--for example:
    #
    #   `curl -v --request POST http://localhost:8086/api/v2/query/analyze`
    # 
    #   In Cloud API docs, the UI replaces the hostname and port with the Cloud URL.
    #
    # - Use "standard" InfluxDB environment variable names as placeholders--for example:
    #
    #    `--header "Authorization: Token INFLUX_TOKEN"`
    # 
    #   Don't wrap placeholders in braces or brackets (`{}`, `<>`) unless these
    #   characters are required in your code (for example, string interpolation).
    # 
    # For more information about the x-codeSamples extension, see https://redocly.com/docs/redoc/redoc-vendor-extensions/#x-codesamples.
    x-codeSamples:
      - lang: Shell
        label: 'cURL'
        source: |
          <!--- Shell code sample that uses cURL. --->
          curl -v --request POST \
          "http://localhost:8086/api/v2/query/analyze" \
          --header "Authorization: Token INFLUX_TOKEN" \
          --header 'Content-type: application/json' \
          --header 'Accept: application/json' \
          --data-binary @- << EOF | jq .
            { "query": "from(foo: \"iot_center\")\
                        |> range(start: -90d)\
                        |> filter(fn: (r) => r._measurement == \"environment\")",
              "type": "flux"
            }
          EOF
      - lang: Shell
        label: 'go tool pprof'
        source: |
          <!--- Shell code sample that uses a specialized command line tool. --->
          # Analyze a profile in interactive mode.
  
          go tool pprof http://localhost:8086/debug/pprof/allocs
  
          # `pprof` returns the following prompt:
          #   Entering interactive mode (type "help" for commands, "o" for options)
          #   (pprof)
  
          # At the prompt, get the top N memory allocations.
  
          (pprof) top10