openapi.yaml

openapi: 3.0.3
info:
  contact:
    email: tagtuna@gmail.com
    name: Tagbase Dev Team
    url: https://github.com/tagbase/tagbase-server/issues
  description: |
    tagbse-server provides HTTP endpoints for ingestion of various files \
    into a Tagbase SQL database. Input file support currently includes eTUFF (see [here](https://doi.org/10.6084/m9.figshare.10032848.v4) \
    and [here](https://doi.org/10.6084/m9.figshare.10159820.v1)). The REST API complies with [OpenAPI v3.0.3](https://spec.openapis.org/oas/v3.0.3.html).
  license:
    name: Apache License v2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: TODO
  title: tagbase-server API
  version: v0.14.0
servers:
- description: Local development tagbase-server
  url: https://localhost/tagbase/api/v0.14.0
- description: ICCAT Test tagbase-server
  url: https://162.13.162.49/tagbase/api/v0.14.0
tags:
- description: Ingestion operations.
  name: ingest
- description: Tag Operations.
  name: tags
paths:
  /ingest:
    get:
      description: Get network accessible file and execute ingestion
      operationId: ingest_get
      parameters:
      - description: Location of a network accessible (file, ftp, http, https)
          file e.g. 'file:///usr/src/app/data/eTUFF-sailfish-117259.txt'.
        explode: true
        in: query
        name: file
        required: true
        schema:
          maxLength: 100
          minLength: 10
          pattern: ^(?!\s*$).+
          type: string
        style: form
      - $ref: '#/components/parameters/notes'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/version'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ingest200'
          description: A success message confirming ingestion.
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
          description: Internal tagbase-server error. Contact admin detailed in openapi.yaml.
      summary: Get network accessible file and execute ingestion
      tags:
      - ingest
      x-openapi-router-controller: tagbase_server.controllers.ingest_controller
    post:
      description: Post a local file and perform a ingest operation
      operationId: ingest_post
      parameters:
      - $ref: '#/components/parameters/filename'
      - $ref: '#/components/parameters/notes'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/version'
      requestBody:
        content:
          application/octet-stream:
            schema:
              description: Compressed binary e.g. zip file containing one or more eTUFF files
              format: binary
              maxLength: 1000000000
              minLength: 1
              type: string
          text/plain:
            schema:
              description: Plain text eTUFF file
              format: binary
              maxLength: 1000000000
              minLength: 1
              type: string
        required: true
        x-body-name: body
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ingest200'
          description: A success message confirming ingestion.
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
          description: Internal tagbase-server error. Contact admin detailed in openapi.yaml.
      summary: Post a local file and perform a ingest operation
      tags:
      - ingest
      x-codegen-request-body-name: body
      x-openapi-router-controller: tagbase_server.controllers.ingest_controller
  /tags:
    delete:
      description: Delete all tags
      operationId: delete_tags
      responses:
        "204":
          description: Successful delete operation.
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
          description: Internal tagbase-server error. Contact admin detailed in openapi.yaml.
      summary: Delete all tags
      tags:
      - tags
      x-openapi-router-controller: tagbase_server.controllers.tags_controller
    get:
      description: Get information about all tags
      operationId: list_tags
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tags200'
          description: A success message confirming ingestion.
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
          description: Internal tagbase-server error. Contact admin detailed in openapi.yaml.
      summary: Get information about all tags
      tags:
      - tags
      x-openapi-router-controller: tagbase_server.controllers.tags_controller
  /tags/{tag_id}:
    parameters:
      - $ref: '#/components/parameters/tagId'
    delete:
      description: Delete an individual tag
      operationId: delete_tag
      responses:
        "204":
          description: Successful delete operation.
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
          description: Internal tagbase-server error. Contact admin detailed in openapi.yaml.
      summary: Delete an individual tag
      tags:
      - tags
      x-openapi-router-controller: tagbase_server.controllers.tags_controller
    get:
      description: Get information about an individual tag
      operationId: get_tag
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag200'
          description: A success message confirming ingestion.
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
          description: Internal tagbase-server error. Contact admin detailed in openapi.yaml.
      summary: Get information about an individual tag
      tags:
      - tags
      x-openapi-router-controller: tagbase_server.controllers.tags_controller
  /tags/{tag_id}/subs/{sub_id}:
    parameters:
      - $ref: '#/components/parameters/subId'
      - $ref: '#/components/parameters/tagId'
    delete:
      description: Delete a tag submission
      operationId: delete_sub
      responses:
        "204":
          description: Successful delete operation.
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
          description: Internal tagbase-server error. Contact admin detailed in openapi.yaml.
      summary: Delete a tag submission
      tags:
      - tags
      x-openapi-router-controller: tagbase_server.controllers.tags_controller
    put:
      description: Update a tag submission
      operationId: replace_tag
      parameters:
      - $ref: '#/components/parameters/notes'
      - $ref: '#/components/parameters/version'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagPut200'
          description: A success message confirming ingestion.
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
          description: Internal tagbase-server error. Contact admin detailed in openapi.yaml.
      summary: Update the 'notes' and/or 'version' associated with a tag submission
      tags:
      - tags
      x-openapi-router-controller: tagbase_server.controllers.tags_controller
components:
  parameters:
    filename:
      description: Free-form text field to explicitly define the name of the file to be persisted
      explode: true
      in: query
      name: filename
      required: true
      schema:
        maxLength: 100
        minLength: 1
        pattern: ^(?!\s*$).+
        type: string
      style: form
    subId:
      description: Existing submission id for an existing tag
      explode: true
      in: path
      name: sub_id
      required: true
      schema:
        type: integer
    tagId:
      description: Existing tag id
      explode: true
      in: path
      name: tag_id
      required: true
      schema:
        type: integer
    notes:
      description: Free-form text field where details of submitted eTUFF file for ingest can be provided e.g. submitter name, etuff data contents (tag metadata and measurements + primary position data, or just secondary solution-positional meta/data)
      explode: true
      in: query
      name: notes
      required: false
      schema:
        maxLength: 10000
        minLength: 1
        pattern: ^(?!\s*$).+
        type: string
      style: form
    type:
      description: Type of file to be ingested, defaults to 'etuff'
      explode: true
      in: query
      name: type
      required: false
      schema:
        default: etuff
        enum:
          - etuff
          - netcdf
        type: string
      style: form
    version:
      description: Version identifier for the eTUFF tag data file ingested
      explode: true
      in: query
      name: version
      required: false
      schema:
        maxLength: 10
        minLength: 1
        pattern: ^(?!\s*$).+
        type: string
      style: form
  schemas:
    filename:
      description: Full name and extension of the ingested eTUFF tag data file
      example: "eTUFF-sailfish-117259_2.txt"
      title: filename
      type: string
    tag_id:
      description: Unique numeric Tag ID associated with the ingested tag eTUFF data file
      example: 3
      type: integer
    ErrorContainer:
      description: 'An error response for an operation.'
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          maxItems: 100
          description: 'The array of error entries associated with the error response'
          items:
            $ref: '#/components/schemas/Error'
        trace:
          description: 'The error trace information.'
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          type: string
    Error:
      description: 'An error response entry.'
      type: object
      properties:
        code:
          description: 'The error code.'
          type: string
          enum:
            - 'internal_server_error'
            - 'bad_request'
            - 'unauthorized'
            - 'service_unavailable'
        message:
          description: 'The error message.'
          type: string
        more_info:
          description: 'Additional info about the error.'
          type: string
    Ingest200:
      description: HTTP 200 success response
      example:
        code: "200"
        elapsed: '0:00:06.506691'
        message: Data file eTUFF-sailfish-117259.txt successfully ingested into Tagbase
          DB.
      properties:
        code:
          description: HTTP status code
          example: "200"
          type: string
        elapsed:
          description: Elapsed time for the operation
          type: string
        message:
          description: A string detailing specifics of an HTTP operation
          example: Data file eTUFF-sailfish-117259.txt successfully ingested into
            Tagbase DB.
          type: string
      title: Ingest200
      type: object
    Metadata:
      description: Contains the ingested tag metadata consistent with the eTUFF specification
      example:
        person_owner: John Do
        owner_contect: john@do.net
        manufacturer: telemetry inc.
        model: new_gen
        attachment_method: anchor
      type: object
      additionalProperties:
        type: string
    Tag200:
      description: Information for a given tag
      example:
        tag:
        - dataset_id: 1
          date_time: '2022-04-01T04:58:21.319061+00:00'
          filename: 'eTUFF-sailfish-117259_2.txt'
          hash_sha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b977'
          metadata:
            person_owner: John Do
            owner_contect: john@do.net
            manufacturer: telemetry inc.
            model: new_gen
            attachment_method: anchor
          notes: 'Ingested by admin on 2022-06-01 for Sailfish tagging campaign.'
          submission_id: 5
          tag_id: 3
          version: '1'
        - dataset_id: 1
          date_time: '2022-06-01T05:39:46.896088+00:00'
          filename: 'eTUFF-sailfish-117259_2.txt'
          hash_sha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
          metadata:
            person_owner: Jane Do
            owner_contect: jane@do.net
            manufacturer: telemetry inc.
            model: newer_gen
            attachment_method: anchor
          notes: 'Ingested by admin on 2022-06-01 for version 2 of the Sailfish tagging campaign.'
          submission_id: 6
          tag_id: 3
          version: '2'
      properties:
        tag:
          description: List containing one or more submissions for a given tag
          items:
            $ref: '#/components/schemas/TagSubmission'
          minItems: 1
          maxItems: 100
          type: array
      title: Tag200
      type: object
    TagPut200:
      description: HTTP 200 success response
      example:
        code: "200"
        message: Tag '1' submission '5' successfully updated.
      properties:
        code:
          description: HTTP status code
          example: "200"
          type: string
        message:
          description: A string detailing specifics of an HTTP operation
          example: Tag '1' submission '5' successfully updated.
          type: string
      title: TagPut200
      type: object
    Tag:
      description: Unique numeric Tag ID associated with the ingested tag eTUFF data file
      example:
        tag_id: 1
        filename: eTUFF-sailfish-117259_2.txt
      properties:
        tag_id:
          $ref: '#/components/schemas/tag_id'
        filename:
          $ref: '#/components/schemas/filename'
      type: object
    TagSubmission:
      type: object
      properties:
        dataset_id:
          description: The primary key from the Dataset relation
          example: 1
          type: integer
        date_time:
          description: Local datetime stamp at the time of eTUFF tag data file ingestion
          example: '2022-04-01T04:58:21.319061+00:00'
          #format: date
          #pattern: '^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?(([+-]\d\d:\d\d)|Z)?$'
          type: string
        filename:
          $ref: '#/components/schemas/filename'
        hash_sha256:
          description: SHA256 hash representing the contents of the submission eTUFF file
          example: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
        notes:
          description: Free-form text field where details of submitted eTUFF file for ingest can be provided e.g. submitter name, etuff data contents (tag metadata and measurements + primary position data, or just secondary solutionpositional meta/data)
          example: "Ingested by admin on XXXX-XX-XX to back-process campaign XYZ."
          type: string
        submission_id:
          description: Unique numeric ID assigned upon submission of a tag eTUFF data file for ingest/importation into Tagbase
          example: 5
          type: integer
        tag_id:
          $ref: '#/components/schemas/tag_id'
        version:
          description: Version identifier for the eTUFF tag data file ingested
          example: "1"
          type: string
    Tags200:
      description: Response detailing all available unique tags and associated filename
      example:
        count: 2
        tags:
        - tag_id: 1
          filename: eTUFF-sailfish-117259_2.txt
        - tag_id: 2
          filename: eTUFF-sailfish-117259.txt
      properties:
        count:
          description: Total count of unique tags
          example: 2
          type: integer
        tags:
          description: List of unique numeric Tag IDs and associated filename
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          minItems: 1
          maxItems: 100000
      title: Tags200
      type: object