swagger.yaml

swagger: '2.0'

info:
  version: "0.0.0"
  title: Dashboard API
schemes:
  - https
securityDefinitions:
  api_key:
    type: apiKey
    name: api_key
    in: header
    description: |
      API Key should be passed as an authorization Header.

      The value for the Authorization header is expected to have the prefix "Token" or "Bearer".

      Samples using curl
      ```
        curl --header "Authorization: Token token=09e9e1cff7e4" http://dashboard.gov.au/api/v1/datasets
        curl --header "Authorization: Bearer 09e9e1cff7e4" http://dashboard.gov.au/api/v1/datasets/1/datapoints
      ```
paths:
  /dashboards/{id}:
    put:
      summary: |
        Updates an existing `Dashboard`
      description: |

        Sample curl requests
        ```
        ```
      security:
       - api_key: []
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: |
            Dashboard object fields to be updated.
          required: true
          schema:
            $ref: "#/definitions/Dashboard"
        - in: path
          name: id
          description: ID of Datapoint
          required: true
          type: integer
          format: int64
      responses:
        "404":
          description: Dashboard not found
        "200":
          description: Success
          schema:
            $ref: "#/definitions/DashboardEntity"
        "400":
          description: Input or Validation Error
          schema:
            $ref: "#/definitions/Error"
  /dashboards/{dashboard_id}/widgets/{id}:
    put:
      summary: |
        Updates an existing `Widget` in the idenitfied `Dashboard`
      description: |

        Sample curl requests
        ```
        ```
      security:
       - api_key: []
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: |
            Widget object fields to be updated.
          required: true
          schema:
            $ref: "#/definitions/Widget"
        - in: path
          name: dashboard_id
          description: ID of Dashboard
          required: true
          type: integer
          format: int64
        - in: path
          name: id
          description: ID of Widget
          required: true
          type: integer
          format: int64
      responses:
        "404":
          description: Dashboard or Widget not found
        "200":
          description: Success
          schema:
            $ref: "#/definitions/WidgetEntity"
        "400":
          description: Input or Validation Error
          schema:
            $ref: "#/definitions/Error"
  /datasets/{id}:
    put:
      summary: |
        Updates an existing `Dataset`
      description: |

        Sample curl requests
        ```
        ```
      security:
       - api_key: []
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: |
            Dataset object fields to be updated.
          required: true
          schema:
            $ref: "#/definitions/Dataset"
        - in: path
          name: id
          description: ID of Dataset
          required: true
          type: integer
          format: int64
      responses:
        "404":
          description: Dataset not found
        "200":
          description: Success
          schema:
            $ref: "#/definitions/DatasetEntity"
        "400":
          description: Input or Validation Error
          schema:
            $ref: "#/definitions/Error"
  /datasets/{datasetId}/datapoints:
    post:
      summary: |
        Creates a new `Datapoint` in the identified `Dataset`
      description: |

        Sample curl requests
        ```
        curl --header "Authorization: Token token=09e9e1cff7e4" --data '{"datapoints": { "ts": "2016-01-01T01:01:01.111Z", "value": "42"}}' http://dashboard.gov.au/api/v1/datasets/1/datapoints
        curl --header "Authorization: Bearer 09e9e1cff7e4" --data '{ "ts": "2016-01-01T01:01:01.111Z", "value": "42"}' http://dashboard.gov.au/api/v1/datasets/1/datapoints
        ```
      security:
       - api_key: []
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: |
            An array of Datapoint objects to be created

            Only ts field is required for creation, value can be null

            Note that this endpoint also accepts a single datapoint, seem the samples and documentation.
          required: true
          schema:
            type: array
            items:
              $ref: "#/definitions/Datapoint"
        - in: path
          name: datasetId
          description: ID of Dataset
          required: true
          type: integer
          format: int64
      responses:
        "404":
          description: Dataset not found
        "201":
          description: Datapoint created.
          schema:
            $ref: "#/definitions/DatapointEntity"
        "400":
          description: Input or Validation Error
          schema:
            $ref: "#/definitions/Error"
    get:
      summary: |
        Returns an array of last 999 Datapoints belonging to identified Dataset
      description: |

        Sample curl requests
        ```
        curl --header "Authorization: Token token=09e9e1cff7e4" http://dashboard.gov.au/api/v1/datasets/1/datapoints/
        curl --header "Authorization: Bearer 09e9e1cff7e4" http://dashboard.gov.au/api/v1/datasets/1/datapoints/
        ```
      security:
       - api_key: []
      produces:
        - application/json
      parameters:
        - in: path
          name: datasetId
          description: ID of Dataset
          required: true
          type: integer
          format: int64
      responses:
        "404":
          description: Dataset not found
        "200":
          description: Success
          schema:
            type: array
            items:
              $ref: "#/definitions/Datapoint"
  /datasets/{datasetId}/datapoints/{id}:
    get:
      summary: |
        Finds a datapoint by ID
      description: |

        Sample curl requests
        ```
        curl --header "Authorization: Token token=09e9e1cff7e4" http://dashboard.gov.au/api/v1/datasets/1/datapoints/1
        ```

        ```
        curl --header "Authorization: Bearer 09e9e1cff7e4" http://dashboard.gov.au/api/v1/datasets/1/datapoints/1
        ```
      security:
       - api_key: []
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          description: ID of Datapoint
          required: true
          type: integer
          format: int64
        - in: path
          name: datasetId
          description: ID of Dataset
          required: true
          type: integer
          format: int64
      responses:
        "404":
          description: Dataset or Datapoint not found
        "200":
          description: Success
          schema:
            $ref: "#/definitions/DatapointEntity"
    put:
      summary: |
        Updates an existing `Datapoint` in the identified `Dataset`
      description: |

        Sample curl requests
        ```
        curl --header "Authorization: Token token=09e9e1cff7e4" --data 'datapoint={ "ts": "2016-01-01T01:01:01.111Z", "value": "42"}' http://dashboard.gov.au/api/v1/datasets/1/datapoints/1
        curl --header "Authorization: Bearer 09e9e1cff7e4" --data 'datapoint={ "ts": "2016-01-01T01:01:01.111Z", "value": "42"}' http://dashboard.gov.au/api/v1/datasets/1/datapoints/1
        ```
      security:
       - api_key: []
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: |
            Datapoint object fields to be updated.
            In general, do not update Datapoints.
            The preference is to delete,and create a new Datapoint
          required: true
          schema:
            $ref: "#/definitions/Datapoint"
        - in: path
          name: datasetId
          description: ID of Dataset
          required: true
          type: integer
          format: int64
        - in: path
          name: id
          description: ID of Datapoint
          required: true
          type: integer
          format: int64
      responses:
        "404":
          description: Dataset or Datapoint not found
        "200":
          description: Success
          schema:
            $ref: "#/definitions/DatapointEntity"
        "400":
          description: Invalid data
          schema:
            $ref: "#/definitions/Error"
definitions:
  DashboardEntity:
    description: |
      Dashboard Entity as recorded in the database
    type: object
    required:
      - name
      - description
      - target_users
    properties:
      id:
        type: number
        format: int64
      name:
        type: string
      description:
        type: string
      target_users:
        type: string
      notes:
        type: string
      url:
        type: string
      display_hero:
        type: boolean
      display_kpis:
        type: boolean
      published_at:
        type: string
        format: date-time
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time
  Dashboard:
    description: Dashboard fields for Create or Update
    type: object
    required:
      - name
      - description
      - target_users
    properties:
      name:
        type: string
      description:
        type: string
      target_users:
        type: string
      notes:
        type: string
      url:
        type: string
      published_at:
        type: string
        format: date-time
  WidgetEntity:
    description: |
      Widget Entity as recorded in the database
    type: object
    required:
      - name
      - units
      - last_updated_at
    properties:
      id:
        type: number
        format: int64
      dashboard_id:
        type: number
        format: int64
      row:
        type: number
        format: int32
      pos:
        type: number
        format: int32
      name:
        type: string
      description:
        type: string
      options:
        type: object
        description: |
          Options are stored as Key/Value records in the database
      size:
        type: string
      units:
        type: string
      type:
        type: string
      is_hero:
        type: boolean
      last_updated_at:
        type: string
        format: date-time
        description: |
          Time to be used to display when the Chart was last updated.
          Not to be confused with updated_at, which stores when the Widget Entity itself was last updated.
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time
  Widget:
    description: |
      Widget fields for Create or Update
    type: object
    required:
      - name
      - description
      - units
      - last_updated_at
    properties:
      name:
        type: string
      description:
        type: string
      units:
        type: string
      last_updated_at:
        type: string
        format: date-time
  DatasetEntity:
    description: |
      Dataset Entity as recorded in the database
    type: object
    required:
      - name
      - units
    properties:
      id:
        type: number
        format: int64
      name:
        type: string
      units:
        type: string
        enum: ["%", "$", "n", "s", "i", "f"]
      notes:
        type: string
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time
  Dataset:
    description: |
      Dataset fields for Create or Update
    type: object
    required:
      - name
      - label
      - units
    properties:
      name:
        type: string
      label:
        type: string
      units:
        type: string
        enum: ["%", "$", "n", "s", "i", "f"]
      notes:
        type: string
  DatapointEntity:
    description: |
      Datapoint Entity as recorded in the database
    type: object
    required:
      - id
      - ts
      - created_at
      - updated_at
    properties:
      id:
        type: number
        format: int64
      ts:
        type: string
        format: date-time
      value:
        type: number
        format: double
        description: |
          Values are numeric, and encoded as strings to avoid precision errors.
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time
  Datapoint:
    type: object
    required:
      - ts
      - value
    properties:
      ts:
        type: string
        format: date-time
      value:
        type: string
        format: double
        description: |
          Values are numeric, and encoded as strings to avoid precision errors.

  Error:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: string
      message:
        type: string