Add htsget 1.2.0, OpenAPI v3.0.2 spec

pub/htsget-openapi.yaml

@@ -0,0 +1,331 @@
+openapi: 3.0.2
+servers:
+  - description: htsget genomics api
+    url: "htsget/1"
+info:
+  description: "This data retrieval API bridges from existing genomics bulk data transfers to a client/server model"
+  version: "1.2.0"
+  title: htsget
+  contact:
+    name: GA4GH
+    email: security-notification@ga4gh.org
+externalDocs:
+  description: htsget specification
+  url: https://samtools.github.io/hts-specs/htsget.html
+paths:
+  /reads/{id}:
+    get:
+      summary: Gets the reads from a pre-indexed id
+      operationId: searchReadId
+      description: |
+        Searches a pre-indexed object id.
+      parameters:
+        - in: "path"
+          name: id
+          description: identifier of the read object
+          required: true
+          schema:
+            type: string
+        - in: "query"
+          name: format
+          description: File format, BAM (default), CRAM.
+          example: "BAM"
+          required: false
+          schema:
+            type: string
+        - in: "query"
+          name: class
+          description: Request different classes of data (such as header or body).
+          example: "header"
+          required: false
+          schema:
+            type: string
+        - in: "query"
+          name: referenceName
+          description: Reference sequence name
+          example: "chr1"
+          required: false
+          schema:
+            type: string
+        - in: "query"
+          name: start
+          description: The start position of the range on the reference, 0-based, inclusive.
+          example: "12312"
+          required: false
+          schema:
+            type: integer
+            format: int64
+            minimum: 0
+        - in: "query"
+          name: end
+          description: The end position of the range on the reference, 0-based exclusive.
+          example: "99999"
+          required: false
+          schema:
+            type: integer
+            format: int64
+            minimum: 0
+        - in: "query"
+          name: fields
+          description: A list of fields to include, such as QNAME, FLAG, RNAME, etc...
+          example: "fields=QNAME,RNAME"
+          required: false
+          schema:
+            enum:
+              - "QNAME"
+              - "FLAG"
+              - "RNAME"
+              - "POS"
+              - "MAPQ"
+              - "CIGAR"
+              - "RNEXT"
+              - "PNEXT"
+              - "TLEN"
+              - "SEQ"
+              - "QUAL"
+            type: string
+        - in: "query"
+          name: tags
+          description: A comma separated list of tags to include, by default all.
+          example: "cancer,melanoma"
+          required: false
+          schema:
+            type: string
+        - in: "query"
+          name: notags
+          description: A comma separated list of tags to exclude, default none.
+          example: "normal,healthy"
+          required: false
+          schema:
+            type: string
+
+# Cannot reuse those since responses does not accept $ref directly, yet:
+# https://github.com/OAI/OpenAPI-Specification/issues/1586
+      responses:
+        '200':
+          description: results matching criteria
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IdResponse'
+              example:
+                {
+                   "htsget" : {
+                      "format" : "BAM",
+                      "urls" : [
+                         {
+                            "url" : "https://htsget.blocksrv.example/sample1234/run1.bam",
+                            "headers" : {
+                               "Authorization" : "Bearer xxxx",
+                               "Range" : "bytes=2744831-9375732"
+                            },
+                            "class" : "body"
+                         }
+                      ]
+                   }
+                }
+        '400':
+          description: Something went wrong
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/UnsupportedFormat'
+                  - $ref: '#/components/schemas/InvalidInput'
+                  - $ref: '#/components/schemas/InvalidRange'
+        '401':
+          description: Authorization provided is invalid
+        '403':
+          description: Authorization is required to access the resource
+        '404':
+          $ref: '#/components/schemas/NotFound'
+        '500':
+          description: Internal Server Error
+        default:
+          description: Internal Server Error
+
+
+      security:
+        - htsget_auth:
+          - read:genomic_reads
+
+
+  /variants/{id}:
+    get:
+      summary: Gets the variants from a pre-indexed id
+      operationId: searchVariantId
+      description: Searches a pre-indexed object id.
+      parameters:
+        - in: "path"
+          name: id
+          description: identifier of the variant object
+          required: true
+          schema:
+            type: string
+        - in: "query"
+          name: format
+          description: File format, VCF (default), BCF.
+          example: "VCF"
+          required: false
+          schema:
+            type: string
+        - in: "query"
+          name: class
+          description: Request different classes of data (such as header or body).
+          example: "body"
+          required: false
+          schema:
+            type: string
+        - in: "query"
+          name: referenceName
+          description: Reference sequence name
+          example: "chr1"
+          required: false
+          schema:
+            type: string
+        - in: "query"
+          name: start
+          description: The start position of the range on the reference, 0-based, inclusive.
+          example: "12312"
+          required: false
+          schema:
+            type: integer
+            format: int64
+            minimum: 0
+        - in: "query"
+          name: end
+          description: The end position of the range on the reference, 0-based exclusive.
+          example: "99999"
+          required: false
+          schema:
+            type: integer
+            format: int64
+            minimum: 0
+        - in: "query"
+          name: tags
+          description: A comma separated list of tags to include, by default all.
+          example: "cancer,melanoma"
+          required: false
+          schema:
+            type: string
+        - in: "query"
+          name: notags
+          description: A comma separated list of tags to exclude, default none.
+          example: "normal,skin"
+          required: false
+          schema:
+            type: string
+
+      responses:
+        '200':
+          description: results matching criteria
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IdResponse'
+              example:
+                {
+                   "htsget" : {
+                      "format" : "VCF",
+                      "urls" : [
+                         {
+                            "url" : "https://htsget.blocksrv.example/sample1234/variants1.vcf",
+                            "headers" : {
+                               "Authorization" : "Bearer xxxx",
+                               "Range" : "bytes=2744831-9375732"
+                            },
+                            "class" : "body"
+                         }
+                      ]
+                   }
+                }
+        '400':
+          description: Something went wrong
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/UnsupportedFormat'
+                  - $ref: '#/components/schemas/InvalidInput'
+                  - $ref: '#/components/schemas/InvalidRange'
+        '401':
+          description: Authorization provided is invalid
+        '403':
+          description: Authorization is required to access the resource
+        '404':
+          $ref: '#/components/schemas/NotFound'
+        '500':
+          description: Internal Server Error
+        default:
+          description: Internal Server Error
+
+      security:
+        - htsget_auth:
+          - read:genomic_variants
+
+components:
+  schemas:
+    IdResponse:
+      $ref: '#/components/schemas/htsgetResponse'
+
+    htsgetResponse:
+      type: object
+      properties:
+        htsget:
+          type: object
+          required:
+            - format
+            - urls
+          properties:
+            format:
+              type: string
+              example:
+                "BAM"
+            urls:
+              $ref: '#/components/schemas/htsgetUrlsHeaders'
+
+            md5:
+              type: string
+              example: "8a6049fad4943ff4c6de5c22df97d001"
+
+
+    htsgetUrlsHeaders:
+      type: array
+      example: 
+        - url: "data:application/vnd.ga4gh.vcf;base64,QkFNAQ=="
+        - url: "https://htsget.blocksrv.example/sample1234/run1.bam"
+          headers:
+            "Authorization": "Bearer xxxxx"
+            "Range": "bytes=65536-1003750"
+      items:
+        $ref: '#/components/schemas/urlsItems'
+
+    urlsItems:
+      type: object
+      required:
+        - url
+      properties:
+        url:
+          type: string
+        headers:
+          type: object
+
+    UnsupportedFormat:
+      description: The requested file format is not supported by the server
+    InvalidInput:
+      description: The request parameters do not adhere to the specification
+    InvalidRange:
+      description: The requested range cannot be satisfied
+    NotFound:
+      description: The resource requested was not found
+
+  securitySchemes:
+    htsget_auth:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://example.com/api/oauth/dialog
+          tokenUrl: https://example.com/api/oauth/token
+          scopes:
+            read:genomic_reads: read access to genomic reads
+            read:genomic_variants: read access to genomic variants