openapi: 3.0.0
servers:
  - url: '/refget/1'
info:
  description: >-
    System for retrieving sequence and metadata concerning a reference sequence
    object by hash identifiers
  version: '2.0.0'
  title: refget API
  contact:
    name: GA4GH Security Notifications
    email: security-notification@ga4gh.org
    url: https://www.ga4gh.org/
tags:
  - name: Metadata
    description: Services linked to retrieving metadata from an identifier
  - name: Sequence
    description: Services linked to fetching sequence from an identifier
  - name: Other
    description: Additional services
paths:
  /sequence/service-info:
    get:
      summary: Retrieve a summary of features this API deployment supports
      operationId: serviceInfo
      tags:
        - Other
      responses:
        '200':
          description: Display of all known configurations for a service deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefgetServiceInfo'
        '415':
          $ref: '#/components/responses/BadFormat'
  '/sequence/{id}':
    get:
      summary: Get a sequence from a hash
      operationId: sequence
      description: |
        Retrieve a reference sequence using a hash function
      tags:
        - Sequence
      parameters:
        - in: path
          name: id
          description: The identifier to use. Should be a checksum hash identifier
          required: true
          schema:
            type: string
            default: 6681ac2f62509cfc220d78751b8dc524
        - in: query
          name: start
          description: Request a subsequence of the data (0-based)
          schema:
            type: integer
            format: int32
            minimum: 0
        - in: query
          name: end
          description: Request a subsequence of the data by specifying the end
          schema:
            type: integer
            format: int32
            minimum: 1
        - in: header
          name: Range
          required: false
          description: >-
            Specify a substring as a single HTTP Range.
            One byte range is permitted, and is 0-based inclusive.
            For example, 'Range: bytes=0-9' corresponds to '?start=0&end=10'.
          schema:
            type: string
      responses:
        '200':
          description: >-
            Successful retrieval of sequence. Returned as a single string with
            no line breaks
          content:
            text/plain:
              schema:
                type: string
                example: >-
                  MSSPTPPGGQRTLQKRKQGSSQKVAASAPKKNTNSNNSILKIYSDEATGLRVDPLVVLFLAVGFIFSVVALHVISKVAGKLF
        '206':
          description: Successful retrieval of subsequence as a single string with no line breaks
        '302':
          description: Redirecting the client where the sequence can be retrieved
        '303':
          description: Redirecting the client where the sequence can be retrieved
        '307':
          description: Redirecting the client where the sequence can be retrieved
        '400':
          description: Invalid input; normally due to range parameter usage
        '404':
          description: Sequence was not found
        '415':
          $ref: '#/components/responses/BadFormat'
        '416':
          description: Invalid range request specified
        '501':
          description: The specified request is not supported by the server
  '/sequence/{id}/metadata':
    get:
      summary: Get reference metadata from a hash
      description: Retrieve a metadata about a reference sequence using a hash identifier
      operationId: metadata
      tags:
        - Metadata
      parameters:
        - in: path
          name: id
          required: true
          description: The identifier to use. Should be a checksum hash
          schema:
            type: string
            default: 6681ac2f62509cfc220d78751b8dc524
      responses:
        '200':
          description: Successful retrieval of sequence metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
        '404':
          description: Sequence hash was not found
        '415':
          $ref: '#/components/responses/BadFormat'
components:
  responses:
    BadFormat:
      description: The requested data format is not supported by the endpoint
    NotFound:
      description: The requested resource was not found
  schemas:
    Metadata:
      type: object
      description: Holds information about a sequence checksum
      properties:
        metadata:
          type: object
          properties:
            id:
              type: string
              description: Query identifier. Normally the default checksum for a given service
              example: 6681ac2f62509cfc220d78751b8dc524
            md5:
              type: string
              description: MD5 checksum of the reference sequence
              example: 6681ac2f62509cfc220d78751b8dc524
            trunc512:
              type: string
              description: >-
                Truncated, to 48 characters, SHA-512 checksum of the reference
                sequence encoded as a HEX string. No longer a preferred serialisation of the SHA-512
              example: 959cb1883fc1ca9ae1394ceb475a356ead1ecceff5824ae7
            ga4gh:
              type: string
              description: >-
                A ga4gh identifier used to identify the sequence. This is a  
                [base64url](defined in RFC4648 §5) representation of the 1st 24 bytes from a
                SHA-512 digest of normalised sequence. This is the preferred method of 
                representing the SHA-512 sequence digest.
              example: ga4gh:SQ.aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2
            length:
              type: integer
              format: int64
              description: An decimal integer of the length of the reference sequence
            aliases:
              type: array
              items:
                $ref: '#/components/schemas/Alias'
          required:
            - id
            - length
            - md5
            - aliases
    Alias:
      type: object
      description: Allows the assignment of an identifier or alias to a naming authority
      properties:
        alias:
          type: string
          description: Free text alias for a given sequence
          example: chr1
        naming_authority:
          type: string
          description: 'Name of the authority, which issued the given alias'
      required:
        - alias
        - naming_authority
    RefgetServiceInfo:
      allOf:
      - '$ref': https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/develop/service-info.yaml#/components/schemas/Service
      - type: object
        description: Extended capabilities of refget service-info response object
        required:
          - refget
        properties:
          refget:
            type: object
            required:
              - circular_supported
              - algorithms
            properties:
              circular_supported:
                type: boolean
                description: Indicates if the service supports circular location queries
              subsequence_limit:
                type: integer
                format: int64
                nullable: true
                description: Maximum length of sequence which may be requested using start and/or end query parameters
              algorithms:
                type: array
                items:
                  type: string
                  description: An array of strings listing the digest algorithms that are supported
                  example:
                  - md5
                  - ga4gh
              identifier_types:
                type: array
                items:
                  type: string
                  description: An array of strings listing the type of name space that are supported
                  example:
                    - insdc
                    - refseq
                    - ensembl