From 3b747e6678f00633a03971c1a0294905709c73e1 Mon Sep 17 00:00:00 2001 From: Roman Valls Guimera Date: Thu, 21 Feb 2019 13:38:45 +1100 Subject: [PATCH 1/9] Add htsget 1.1.1, OpenAPI v3.0.0 spec --- pub/htsget-openapi.yaml | 263 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 pub/htsget-openapi.yaml diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml new file mode 100644 index 000000000..a2be0bef8 --- /dev/null +++ b/pub/htsget-openapi.yaml @@ -0,0 +1,263 @@ +openapi: 3.0.0 +servers: + - description: htsget genomics api + url: https://virtserver.swaggerhub.com/brainkod/htsget/1.1.1 +info: + description: "This data retrieval API bridges from existing genomics bulk data transfers to a client/server model" + version: "1.1.1" + title: htsget + contact: + name: Roman Valls Guimera + email: brainstorm+htsget@nopcode.org + license: + name: GPLv3 +paths: + /reads: + get: + summary: Gets the reads from a pre-indexed id + operationId: searchReadId + description: | + Searches a pre-indexed object id. + parameters: + - in: "path" + name: identifier of the read object + description: id + 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: referenceName + description: VReference 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: int32 + - 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: int32 + - 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 + + + responses: + '200': + description: results matching criteria + content: + application/json: + schema: + $ref: '#/components/schemas/readIdResponse' + + '400': + description: something went wrong + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponses' + + '500': + description: Unexpected error + + + /variants: + 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: referenceName + description: VReference 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: int32 #XXX: htsget spec says unsigned, swagger is signed + - 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: int32 #XXX: htsget spec says unsigned, swagger is signed + - in: "query" + name: fields + description: A list of variant fields to include, such as INFO, SAMPLE, FORMAT, etc. + example: "fields=INFO,SAMPLE" + required: false + schema: + enum: + - "INFO" + - "SAMPLE" + - "FILTER" + - "FORMAT" + - "ALT" + 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,skin" + required: false + schema: + type: string + + responses: + '200': + description: results matching criteria + content: + application/json: + schema: + $ref: '#/components/schemas/variantIdResponse' + + '400': + description: something went wrong + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponses' + + '500': + description: Unexpected error + +components: + schemas: + readIdResponse: + $ref: '#/components/schemas/htsgetResponse' + + variantIdResponse: + $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.bam;base64,QkFNAQ==" + - url: "data:application/vnd.ga4gh.vcf;base64,QkFNAQ==" + 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 + + # HTTP 400 errors + errorResponses: + oneOf: + - $ref: '#/components/schemas/UnsupportedFormat' + - $ref: '#/components/schemas/InvalidInput' + - $ref: '#/components/schemas/InvalidRange' + + 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 From 867eef90a3fbe8be279cdc8e773bfaaf94be3c0b Mon Sep 17 00:00:00 2001 From: Roman Valls Guimera Date: Thu, 21 Feb 2019 14:48:38 +1100 Subject: [PATCH 2/9] Add barebones authorizationCode Oauth2 flow, should aid/inform code generation --- pub/htsget-openapi.yaml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml index a2be0bef8..d6e2abfd1 100644 --- a/pub/htsget-openapi.yaml +++ b/pub/htsget-openapi.yaml @@ -108,6 +108,10 @@ paths: '500': description: Unexpected error + security: + - htsget_auth: + - read:genomic_reads + /variants: get: @@ -198,6 +202,10 @@ paths: '500': description: Unexpected error + security: + - htsget_auth: + - read:genomic_variants + components: schemas: readIdResponse: @@ -261,3 +269,14 @@ components: description: The request parameters do not adhere to the specification InvalidRange: description: The requested range cannot be satisfied + + 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 From b8497d0bfa1ce17bc8e0dc3d417f1b5d99827588 Mon Sep 17 00:00:00 2001 From: Roman Valls Guimera Date: Thu, 21 Feb 2019 15:03:44 +1100 Subject: [PATCH 3/9] Add explicit URL parameter definition, fix name/description swap in reads endpoint --- pub/htsget-openapi.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml index d6e2abfd1..d26a7f400 100644 --- a/pub/htsget-openapi.yaml +++ b/pub/htsget-openapi.yaml @@ -12,7 +12,7 @@ info: license: name: GPLv3 paths: - /reads: + /reads/{id}: get: summary: Gets the reads from a pre-indexed id operationId: searchReadId @@ -20,8 +20,8 @@ paths: Searches a pre-indexed object id. parameters: - in: "path" - name: identifier of the read object - description: id + name: id + description: identifier of the read object required: true schema: type: string @@ -113,7 +113,7 @@ paths: - read:genomic_reads - /variants: + /variants/{id}: get: summary: Gets the variants from a pre-indexed id operationId: searchVariantId From 09ee68bb1457e2d0b4e56b5e265a509531752d5b Mon Sep 17 00:00:00 2001 From: Roman Valls Guimera Date: Fri, 22 Feb 2019 10:48:26 +1100 Subject: [PATCH 4/9] Change to int64 with minimum 0, unsure if that is really an uint64 though. Change contact information to GA4GH --- pub/htsget-openapi.yaml | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml index d26a7f400..6dee57169 100644 --- a/pub/htsget-openapi.yaml +++ b/pub/htsget-openapi.yaml @@ -7,8 +7,8 @@ info: version: "1.1.1" title: htsget contact: - name: Roman Valls Guimera - email: brainstorm+htsget@nopcode.org + name: GA4GH + email: security-notification@ga4gh.org license: name: GPLv3 paths: @@ -46,7 +46,8 @@ paths: required: false schema: type: integer - format: int32 + format: int64 + minimum: 0 - in: "query" name: end description: The end position of the range on the reference, 0-based exclusive. @@ -54,7 +55,8 @@ paths: required: false schema: type: integer - format: int32 + format: int64 + minimum: 0 - in: "query" name: fields description: A list of fields to include, such as QNAME, FLAG, RNAME, etc... @@ -147,7 +149,8 @@ paths: required: false schema: type: integer - format: int32 #XXX: htsget spec says unsigned, swagger is signed + format: int64 + minimum: 0 - in: "query" name: end description: The end position of the range on the reference, 0-based exclusive. @@ -155,7 +158,8 @@ paths: required: false schema: type: integer - format: int32 #XXX: htsget spec says unsigned, swagger is signed + format: int64 + minimum: 0 - in: "query" name: fields description: A list of variant fields to include, such as INFO, SAMPLE, FORMAT, etc. From 7e70f56fb07ae1f1dace6d2d7e150d582ad70f97 Mon Sep 17 00:00:00 2001 From: Roman Valls Guimera Date: Fri, 17 May 2019 12:39:08 +1000 Subject: [PATCH 5/9] Reference instead of VReference Thanks JMarshall Co-Authored-By: John Marshall --- pub/htsget-openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml index 6dee57169..45c801c7d 100644 --- a/pub/htsget-openapi.yaml +++ b/pub/htsget-openapi.yaml @@ -34,7 +34,7 @@ paths: type: string - in: "query" name: referenceName - description: VReference sequence name + description: Reference sequence name example: "chr1" required: false schema: From fc87823ee1ba13b0cd30edc1450bec150ffb2b76 Mon Sep 17 00:00:00 2001 From: brainstorm Date: Fri, 17 May 2019 12:42:44 +1000 Subject: [PATCH 6/9] Adressing different concerns about the openapi spec --- pub/htsget-openapi.yaml | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml index 6dee57169..5415d6b60 100644 --- a/pub/htsget-openapi.yaml +++ b/pub/htsget-openapi.yaml @@ -9,8 +9,6 @@ info: contact: name: GA4GH email: security-notification@ga4gh.org - license: - name: GPLv3 paths: /reads/{id}: get: @@ -34,7 +32,7 @@ paths: type: string - in: "query" name: referenceName - description: VReference sequence name + description: Reference sequence name example: "chr1" required: false schema: @@ -137,7 +135,7 @@ paths: type: string - in: "query" name: referenceName - description: VReference sequence name + description: Reference sequence name example: "chr1" required: false schema: @@ -160,19 +158,6 @@ paths: type: integer format: int64 minimum: 0 - - in: "query" - name: fields - description: A list of variant fields to include, such as INFO, SAMPLE, FORMAT, etc. - example: "fields=INFO,SAMPLE" - required: false - schema: - enum: - - "INFO" - - "SAMPLE" - - "FILTER" - - "FORMAT" - - "ALT" - type: string - in: "query" name: tags description: A comma separated list of tags to include, by default all. From 5e04acfad1b738dff0bd901e83e426dd371fd11b Mon Sep 17 00:00:00 2001 From: brainstorm Date: Wed, 26 Jun 2019 15:52:04 +1000 Subject: [PATCH 7/9] Bump to 1.2.0 htsget spec, flesh out error messages and other feedback from @mlin (thanks), also add class as an extra attribute. /cc @ohofmann --- pub/htsget-openapi.yaml | 120 ++++++++++++++++++++++++++++++---------- 1 file changed, 90 insertions(+), 30 deletions(-) diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml index 5415d6b60..3f5cc5e9e 100644 --- a/pub/htsget-openapi.yaml +++ b/pub/htsget-openapi.yaml @@ -1,14 +1,17 @@ -openapi: 3.0.0 +openapi: 3.0.2 servers: - description: htsget genomics api - url: https://virtserver.swaggerhub.com/brainkod/htsget/1.1.1 + url: https://virtserver.swaggerhub.com/brainkod/htsget/1.2.0 info: description: "This data retrieval API bridges from existing genomics bulk data transfers to a client/server model" - version: "1.1.1" + 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: @@ -30,6 +33,13 @@ paths: 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 @@ -89,24 +99,51 @@ paths: 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/readIdResponse' - + $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 + description: Something went wrong content: application/json: schema: - $ref: '#/components/schemas/errorResponses' - + 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: Unexpected error + description: Internal Server Error + default: + description: Internal Server Error + security: - htsget_auth: @@ -117,8 +154,7 @@ paths: get: summary: Gets the variants from a pre-indexed id operationId: searchVariantId - description: | - Searches a pre-indexed object id. + description: Searches a pre-indexed object id. parameters: - in: "path" name: id @@ -133,6 +169,13 @@ paths: 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 @@ -179,17 +222,42 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/variantIdResponse' - + $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 + description: Something went wrong content: application/json: schema: - $ref: '#/components/schemas/errorResponses' - + 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: Unexpected error + description: Internal Server Error + default: + description: Internal Server Error security: - htsget_auth: @@ -197,10 +265,7 @@ paths: components: schemas: - readIdResponse: - $ref: '#/components/schemas/htsgetResponse' - - variantIdResponse: + IdResponse: $ref: '#/components/schemas/htsgetResponse' htsgetResponse: @@ -227,8 +292,8 @@ components: htsgetUrlsHeaders: type: array example: - - url: "data:application/vnd.ga4gh.bam;base64,QkFNAQ==" - url: "data:application/vnd.ga4gh.vcf;base64,QkFNAQ==" + - url: "https://htsget.blocksrv.example/sample1234/run1.bam" headers: "Authorization": "Bearer xxxxx" "Range": "bytes=65536-1003750" @@ -245,19 +310,14 @@ components: headers: type: object - # HTTP 400 errors - errorResponses: - oneOf: - - $ref: '#/components/schemas/UnsupportedFormat' - - $ref: '#/components/schemas/InvalidInput' - - $ref: '#/components/schemas/InvalidRange' - 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: From 0619ce6878af42ddc49155c8b02e923bfef46486 Mon Sep 17 00:00:00 2001 From: brainstorm Date: Tue, 3 Sep 2019 08:41:28 +1000 Subject: [PATCH 8/9] Variants example should contain VCF, not BAM --- pub/htsget-openapi.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml index 3f5cc5e9e..43871bd4f 100644 --- a/pub/htsget-openapi.yaml +++ b/pub/htsget-openapi.yaml @@ -226,10 +226,10 @@ paths: example: { "htsget" : { - "format" : "BAM", + "format" : "VCF", "urls" : [ { - "url" : "https://htsget.blocksrv.example/sample1234/run1.bam", + "url" : "https://htsget.blocksrv.example/sample1234/variants1.vcf", "headers" : { "Authorization" : "Bearer xxxx", "Range" : "bytes=2744831-9375732" From aba949c23dc2516588eeb02b9a25fa50fd4bdd9e Mon Sep 17 00:00:00 2001 From: Roman Valls Guimera Date: Mon, 16 Sep 2019 23:20:07 +1000 Subject: [PATCH 9/9] Substitute URL to non-specific one, thanks @jmarshall --- pub/htsget-openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pub/htsget-openapi.yaml b/pub/htsget-openapi.yaml index 43871bd4f..53d6168db 100644 --- a/pub/htsget-openapi.yaml +++ b/pub/htsget-openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.0.2 servers: - description: htsget genomics api - url: https://virtserver.swaggerhub.com/brainkod/htsget/1.2.0 + 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"