openapi: 3.0.1
info:
  title: Data Source Management API
  version: 1.0.0
servers:
  - url: https://api.wiremock.cloud
security:
  - BasicAuth: []
  - OpenID: []
paths:
  /v1/users/{userId}/data-sources:
    parameters:
      - name: userId
        in: path
        description: The ID of the user account making the request.
        required: true
    post:
      description: Create a new data source.
      operationId: createDataSource
      requestBody:
        $ref: "#/components/requestBodies/DataSourceRequestBody"
      responses:
        "201":
          $ref: "#/components/responses/Success"
        "422":
          $ref: "#/components/responses/422"
  /v1/data-sources/{dataSourceId}:
    parameters:
      - name: dataSourceId
        in: path
        description: The ID of the data source to operate on. This is assigned to the
          data source upon creation.
        required: true
    get:
      description: Retrieve a data source.
      operationId: getDataSource
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "404":
          $ref: "#/components/responses/404"
    put:
      description: Update a data source.
      operationId: updateDataSource
      requestBody:
        $ref: "#/components/requestBodies/DataSourceRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "422":
          $ref: "#/components/responses/422"
        "404":
          $ref: "#/components/responses/404"
    delete:
      description: Delete a data source.
      operationId: deleteDataSource
      responses:
        "204":
          description: No content. Data source was deleted.
        "404":
          $ref: "#/components/responses/404"
components:
  securitySchemes:
    OpenID:
      type: openIdConnect
      openIdConnectUrl: https://login.wiremock.cloud/.well-known/openid-configuration
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP basic authentication using username (email address) and password
        (API key).
  requestBodies:
    DataSourceRequestBody:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DataSourceRequest"
          examples:
            Success:
              $ref: "#/components/examples/DataSourceRequestExample"
      required: true
  responses:
    Success:
      description: The data source.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DataSourceResponse"
          examples:
            Success:
              $ref: "#/components/examples/DataSourceResponseExample"
    "422":
      description: Requested data source could not be created/updated/parsed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Errors"
          examples:
            Invalid data:
              value: |
                {
                  "errors": [
                    { "title": "Data source name already exists in organisation", "detail": "A data source with the name \"My data source\" already exists in your organisation." },
                    { "title": "Duplicate columns", "detail": "The data source contains multiple columns with the same name (\"column 1 name\")" },
                    { "title": "Invalid data", "detail": "The data source contains rows with too many columns (row indices: 3)" },
                    { "title": "Invalid data", "detail": "Column \"admin\" (column index 1) contains data that does not adhere to the type \"BOOLEAN\" (row indices: 1)" },
                  ]
                }
    "404":
      description: Data source not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Errors"
          examples:
            Data source not found:
              value: |
                { "errors": [ { "title": "No data source found" } ] }
  schemas:
    DataSourceResponse:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              description: The assigned ID of the data source.
              type: string
        - $ref: "#/components/schemas/BaseDataSource"
    DataSourceRequest:
      allOf:
        - $ref: "#/components/schemas/BaseDataSource"
        - type: object
          required:
            - rows
          properties:
            rows:
              description: "The rows of data. This is an array of arrays, with each outer\
                \ array item representing a row, and each inner array item representing\
                \ a cell in the respective row."
              type: array
              items:
                description: A row of data.
                type: array
                items:
                  description: A single data value.
                  type: string
    BaseDataSource:
      type: object
      required:
        - name
        - columnsMetadata
      properties:
        name:
          description: The name of the data source. Must be unique within your organisation.
          type: string
        columnsMetadata:
          description: Metadata describing the format of each column of the data.
            The order of the column metadata items must be the same as the order of
            the columns in the data.
          type: array
          items:
            description: Metadata for a single column.
            type: object
            required:
              - name
              - type
            properties:
              name:
                description: The name of the column.
                type: string
              type:
                description: An object describing the shape of the data in this column.
                type: object
                required:
                  - name
                properties:
                  name:
                    description: The name of the type.
                    type: string
                    enum:
                      - BOOLEAN
                      - DECIMAL
                      - INTEGER
                      - STRING
                      - DATE
                      - TIME
                      - DATETIME
                  format:
                    description: "The format of the column's data. This is required\
                      \ if and only if type name is `DATE`, `TIME`, and `DATETIME`.\
                      \ Allowed values are `iso8601` or a custom format (see https://docs.wiremock.io/data-sources/managing-data-sources/#date-type).\
                      \ Values of `epoch` (milliseconds since Unix Epoch) and `unix` (seconds since Unix Epoch) are also permitted if and only\
                      \ if type name is `DATETIME`."
                    type: string
                  zoned:
                    description: Required if and only if type name is `TIME` or `DATETIME`.
                      Specifies whether the column data contains a time zone.
                    type: boolean
      additionalProperties: true
    Errors:
      type: object
      properties:
        errors:
          description: A list of errors that caused the failure.
          type: array
          items:
            type: object
            properties:
              title:
                description: The title of the error.
                type: string
              detail:
                description: A detailed message of the error.
                type: string
            additionalProperties: true
  examples:
    DataSourceRequestExample:
      value: |
        {
          "name": "My data source",
          "columnsMetadata": [
            { "name": "fullname", "type": { "name": "STRING" } },
            { "name": "dob", "type": { "name": "DATE", "format": "iso8601" } },
            { "name": "admin", "type": { "name": "BOOLEAN" } },
            { "name": "retryLimit", "type": { "name": "INTEGER" } }
          ],
          "rows": [
            ["Alice S", "1975-05-31", "true", "3"],
            ["Bob B", "1959-11-16", "false", "1"],
            ["Sam M", "1999-07-02", "false", "0"]
          ]
        }
    DataSourceResponseExample:
      value: |
        {
          "id": "abc123",
          "name": "My data source",
          "columnsMetadata": [
            { "name": "fullname", "type": { "name": "STRING" } },
            { "name": "dob", "type": { "name": "DATE", "format": "iso8601" } },
            { "name": "admin", "type": { "name": "BOOLEAN" } },
            { "name": "retryLimit", "type": { "name": "INTEGER" } }
          ]
        }