openapi: 3.0.0
info:
  title: Task API
  version: '1.0'
  description: >-
    The Tidepool API is an HTTP REST API used by Tidepool clients use to
    communicate with the Tidepool Platform.


    For more information, see the [Getting Started](../docs/quick-start.md)
    section.
  contact:
    name: API Support
    url: https://support.tidepool.org/
    email: support@tidepool.org
  license:
    name: BSD-2-Clause
    url: https://github.com/tidepool-org/platform/blob/master/LICENSE
  x-tidepool-service: https://github.com/tidepool-org/platform/task
servers:
  - url: https://external.integration.tidepool.org
    description: integration
  - url: https://api.tidepool.org
    description: production
  - url: https://dev1.dev.tidepool.org
    description: dev1
  - url: https://qa1.development.tidepool.org
    description: qa1
  - url: https://qa2.development.tidepool.org
    description: qa2
security:
  - serverToken: []
tags:
  - name: Internal
    description: APIs intended for internal use by Tidepool.
  - name: Tasks
    description: List, create and manage generic background tasks.
paths:
  /v1/tasks:
    get:
      operationId: ListTasks
      summary: List Tasks
      description: >-
        Returns list of tasks. The list can be filtered with the `name`, `type`,
        or `state` query parameters. It can also be paginated with the `page`
        and `size` query parameters.
      parameters:
        - $ref: '#/components/parameters/name.v1'
        - $ref: '#/components/parameters/task-type.v1'
        - $ref: '#/components/parameters/state.v1'
        - $ref: '#/components/parameters/paginationpage.v1'
        - $ref: '#/components/parameters/paginationsize.v1'
      responses:
        '200':
          $ref: '#/components/responses/Tasks'
        '400':
          $ref: '#/components/responses/badrequest.v1'
        '401':
          $ref: '#/components/responses/unauthorized.v1'
        '500':
          $ref: '#/components/responses/servererror.v1'
      tags:
        - Tasks
        - Internal
    post:
      operationId: CreateTask
      summary: Create New Task
      description: Creates a new task.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newtask.v1'
      responses:
        '200':
          $ref: '#/components/responses/Task'
        '400':
          $ref: '#/components/responses/badrequest.v1'
        '401':
          $ref: '#/components/responses/unauthorized.v1'
        '500':
          $ref: '#/components/responses/servererror.v1'
      tags:
        - Tasks
        - Internal
  /v1/tasks/{taskId}:
    parameters:
      - $ref: '#/components/parameters/id.v1'
    get:
      operationId: GetTask
      summary: Get Task
      description: Returns the task identified by `taskId`.
      responses:
        '200':
          $ref: '#/components/responses/Task'
        '400':
          $ref: '#/components/responses/badrequest.v1'
        '401':
          $ref: '#/components/responses/unauthorized.v1'
        '404':
          $ref: '#/components/responses/notfound.v1'
        '500':
          $ref: '#/components/responses/servererror.v1'
      tags:
        - Tasks
        - Internal
    put:
      operationId: UpdateTask
      summary: Update Task
      description: Updates the task identified by `taskId`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updatetask.v1'
      responses:
        '200':
          $ref: '#/components/responses/Task'
        '400':
          $ref: '#/components/responses/badrequest.v1'
        '401':
          $ref: '#/components/responses/unauthorized.v1'
        '404':
          $ref: '#/components/responses/notfound.v1'
        '500':
          $ref: '#/components/responses/servererror.v1'
      tags:
        - Tasks
        - Internal
    delete:
      operationId: DeleteTask
      summary: Delete Task
      description: Deletes the task identified by `taskId`.
      responses:
        '200':
          description: Success
        '400':
          $ref: '#/components/responses/badrequest.v1'
        '401':
          $ref: '#/components/responses/unauthorized.v1'
        '404':
          $ref: '#/components/responses/notfound.v1'
        '500':
          $ref: '#/components/responses/servererror.v1'
      tags:
        - Tasks
        - Internal
components:
  securitySchemes:
    serverToken:
      description: Tidepool Server Token
      type: apiKey
      name: X-Tidepool-Session-Token
      in: header
  responses:
    Task:
      description: Task
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/task.v1'
    Tasks:
      description: Tasks
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/tasks.v1'
    badrequest.v1:
      description: 400 Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.v1-2'
    unauthorized.v1:
      description: 401 Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.v1-2'
    servererror.v1:
      description: 500 Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.v1-2'
    notfound.v1:
      description: 404 Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.v1-2'
  schemas:
    name.v1:
      title: Task Name
      type: string
    task-type.v1:
      title: Task Type
      type: string
    state.v1:
      title: Task State
      type: string
      enum:
        - pending
        - running
        - failed
        - completed
      example: running
      x-go-type: string
    pagenumber.v1:
      title: Page Number
      description: Page number for pagination
      type: integer
      format: int32
      readOnly: true
      minimum: 0
      default: 0
      example: 0
    pagesize.v1:
      title: Page Size
      description: Page size for pagination
      type: integer
      format: int32
      readOnly: true
      minimum: 1
      maximum: 1000
      default: 100
      example: 42
    task-id.v1:
      title: Task ID
      type: string
      pattern: ^[0-9a-f]{32}$
      minLength: 32
      maxLength: 32
      example: 354b6adc10bc417eb715a8e7b21d6031
    priority.v1:
      title: Task Priority
      type: integer
      format: int32
      minimum: 0
    data.v1:
      title: Task Data
      type: object
      additionalProperties: true
    datetime.v1:
      title: Date/Time
      description: >-
        [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) / [ISO
        8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp
        _with_ timezone information
      type: string
      format: date-time
      example: '2017-02-06T02:37:46Z'
      x-go-type: string
    error.v1:
      title: Task Error(s)
      type: string
    duration.v1:
      title: Task Duration
      type: number
      minimum: 0
    task.v1:
      title: Task
      type: object
      properties:
        id:
          $ref: '#/components/schemas/task-id.v1'
        name:
          $ref: '#/components/schemas/name.v1'
        type:
          $ref: '#/components/schemas/task-type.v1'
        priority:
          $ref: '#/components/schemas/priority.v1'
        data:
          $ref: '#/components/schemas/data.v1'
        availableTime:
          $ref: '#/components/schemas/datetime.v1'
        expirationTime:
          $ref: '#/components/schemas/datetime.v1'
        state:
          $ref: '#/components/schemas/state.v1'
        error:
          $ref: '#/components/schemas/error.v1'
        runTime:
          $ref: '#/components/schemas/datetime.v1'
        duration:
          $ref: '#/components/schemas/duration.v1'
        createdTime:
          $ref: '#/components/schemas/datetime.v1'
        modifiedTime:
          $ref: '#/components/schemas/datetime.v1'
    tasks.v1:
      title: Tasks
      type: array
      items:
        $ref: '#/components/schemas/task.v1'
    error.v1-2:
      title: Error
      type: object
      properties:
        code:
          type: integer
          example: 404
        message:
          type: string
          example: Requested resources was not found
      required:
        - code
        - message
    newtask.v1:
      title: New Task
      type: object
      properties:
        name:
          $ref: '#/components/schemas/name.v1'
        type:
          $ref: '#/components/schemas/task-type.v1'
        priority:
          $ref: '#/components/schemas/priority.v1'
        data:
          $ref: '#/components/schemas/data.v1'
        availableTime:
          $ref: '#/components/schemas/datetime.v1'
        expirationTime:
          $ref: '#/components/schemas/datetime.v1'
      required:
        - name
        - type
        - priority
        - data
        - availableTime
        - expirationTime
    updatetask.v1:
      title: Update Task
      type: object
      properties:
        priority:
          $ref: '#/components/schemas/priority.v1'
        data:
          $ref: '#/components/schemas/data.v1'
        availableTime:
          $ref: '#/components/schemas/datetime.v1'
        expirationTime:
          $ref: '#/components/schemas/datetime.v1'
      required:
        - priority
        - data
        - availableTime
        - expirationTime
  parameters:
    name.v1:
      description: Task Name Filter. Filter by task name
      name: name
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/name.v1'
    task-type.v1:
      description: Task Type Filter. Filter by task type
      name: type
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/task-type.v1'
    state.v1:
      description: Task State Filter. Filter by task state
      name: state
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/state.v1'
    paginationpage.v1:
      description: Page number for pagination
      name: page
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/pagenumber.v1'
    paginationsize.v1:
      description: Page size for pagination
      name: size
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/pagesize.v1'
    id.v1:
      description: Task ID
      name: taskId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/task-id.v1'
