From a44d5df82a37a710a20c28371e5a41e9f9bc7d84 Mon Sep 17 00:00:00 2001 From: Sabela Date: Thu, 17 Jan 2019 17:02:16 +0100 Subject: [PATCH 1/4] Add ERROR value (issue #254) --- beacon.yaml | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/beacon.yaml b/beacon.yaml index cd5509b9..da3ed42d 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -166,6 +166,8 @@ paths: (datasetAlleleResponses) should be included in the response (BeaconAlleleResponse) to this request or not. + Use ERROR to filter out the datasets which return an error. + If null (not specified), the default value of NONE is assumed. in: query required: false @@ -175,6 +177,7 @@ paths: - ALL - HIT - MISS + - ERROR - NONE responses: '200': @@ -428,16 +431,20 @@ components: items: type: string includeDatasetResponses: - description: >- + description: | Indicator of whether responses for individual datasets (datasetAlleleResponses) should be included in the response - (BeaconAlleleResponse) to this request or not. If null (not - specified), the default value of NONE is assumed. + (BeaconAlleleResponse) to this request or not. + + Use ERROR to filter out the datasets which return an error. + + If null (not specified), the default value of NONE is assumed. type: string enum: - ALL - HIT - MISS + - ERROR - NONE BeaconAlleleResponse: type: object From 65d3bdf9825ff947d47bbe08d41d230c2ac9730f Mon Sep 17 00:00:00 2001 From: Sabela Date: Thu, 17 Jan 2019 17:08:07 +0100 Subject: [PATCH 2/4] Fix formatting. --- beacon.yaml | 57 ++++++++++++++++++++++++----------------------------- 1 file changed, 26 insertions(+), 31 deletions(-) diff --git a/beacon.yaml b/beacon.yaml index da3ed42d..9e499138 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -95,7 +95,7 @@ paths: format: int64 minimum: 0 - name: referenceBases - description: > + description: | Reference bases for this variant (starting from `start`). Accepted values: [ACGT]* @@ -109,7 +109,7 @@ paths: type: string pattern: '^([ACGT]+|N)$' - name: alternateBases - description: > + description: | The bases that appear instead of the reference bases. Accepted values: [ACGT]* or N. @@ -123,7 +123,7 @@ paths: type: string pattern: '^([ACGT]+|N)$' - name: variantType - description: > + description: | The `variantType` is used to denote e.g. structural variants. Examples: @@ -150,7 +150,7 @@ paths: schema: type: string - name: datasetIds - description: >- + description: | Identifiers of datasets, as defined in "BeaconDataset". If this field is null/not specified, all datasets should be queried. in: query @@ -161,7 +161,7 @@ paths: items: type: string - name: includeDatasetResponses - description: > + description: | Indicator of whether responses for individual datasets (datasetAlleleResponses) should be included in the response (BeaconAlleleResponse) to this request or not. @@ -202,7 +202,7 @@ paths: schema: $ref: '#/components/schemas/BeaconAlleleResponse' '403': - description: >- + description: | Forbidden (e.g. the resource is protected for all users or the user is authenticated but s/he is not granted for this resource) content: @@ -227,7 +227,7 @@ paths: schema: $ref: '#/components/schemas/BeaconAlleleResponse' '401': - description: >- + description: | Unauthorised (e.g. when an unauthenticated user tries to access a protected resource) content: @@ -235,7 +235,7 @@ paths: schema: $ref: '#/components/schemas/BeaconAlleleResponse' '403': - description: >- + description: | Forbidden (e.g. the resource is protected for all users or the user is authenticated but s/he is not granted for this resource) content: @@ -314,7 +314,7 @@ components: example: 'http://example.org/wiki/Main_Page' alternativeUrl: type: string - description: >- + description: | Alternative URL to the API, e.g. a restricted version of this beacon (RFC 3986 format). example: 'http://example.org/wiki/Main_Page' @@ -327,14 +327,14 @@ components: description: The time the beacon was updated in (ISO 8601 format). example: '2012-07-19 or 2017-01-17T20:33:40Z' datasets: - description: >- + description: | Dataset(s) served by the beacon. minItems: 1 type: array items: $ref: '#/components/schemas/BeaconDataset' sampleAlleleRequests: - description: >- + description: | Examples of interesting queries, e.g. a few queries demonstrating different responses. type: array @@ -388,16 +388,14 @@ components: description: Maximum end coordinate. See startMin. type: integer referenceBases: - description: > - Reference bases for this variant (starting from `start`). Accepted - values: [ACGT]* + description: | + Reference bases for this variant (starting from `start`). Accepted values: [ACGT]* When querying for variants without specific base alterations (e.g. imprecise structural variants with separate variant_type as well as start_min & end_min ... parameters), the use of a single "N" value is required. type: string pattern: '^([ACGT]+|N)$' alternateBases: - description: > - The bases that appear instead of the reference bases. Accepted - values: [ACGT]* or N. + description: | + The bases that appear instead of the reference bases. Accepted values: [ACGT]* or N. Symbolic ALT alleles (DEL, INS, DUP, INV, CNV, DUP:TANDEM, DEL:ME, INS:ME) will be represented in `variantType`. @@ -406,17 +404,14 @@ components: type: string pattern: '^([ACGT]+|N)$' variantType: - description: > + description: | The `variantType` is used to denote e.g. structural variants. Examples: - * DUP: duplication of sequence following `start`; not necessarily in situ - * DEL: deletion of sequence following `start` - Optional: either `alternateBases` or `variantType` is required. type: string assemblyId: @@ -424,7 +419,7 @@ components: type: string example: GRCh38 datasetIds: - description: >- + description: | Identifiers of datasets, as defined in `BeaconDataset`. If this field is null/not specified, all datasets should be queried. type: array @@ -455,12 +450,12 @@ components: description: 'Identifier of the beacon, as defined in `Beacon`.' type: string apiVersion: - description: >- + description: | Version of the API. If specified, the value must match `apiVersion` in Beacon type: string exists: - description: >- + description: | Indicator of whether the given allele was observed in any of the datasets queried. This should be non-null, unless there was an error, in which case `error` has to be non-null. @@ -468,7 +463,7 @@ components: alleleRequest: $ref: '#/components/schemas/BeaconAlleleRequest' datasetAlleleResponses: - description: >- + description: | Indicator of whether the given allele was observed in individual datasets. This should be non-null if `includeDatasetResponses` in the corresponding `BeaconAlleleRequest` is true, and null otherwise. @@ -501,12 +496,12 @@ components: description: URL of the website of the organization (RFC 3986 format). contactUrl: type: string - description: >- + description: | URL with the contact for the beacon operator/maintainer, e.g. link to a contact form (RFC 3986 format) or an email (RFC 2368 format). logoUrl: type: string - description: >- + description: | URL to the logo (PNG/JPG format) of the organization (RFC 3986 format). info: @@ -564,7 +559,7 @@ components: minimum: 0 externalUrl: type: string - description: >- + description: | URL to an external system providing more dataset information (RFC 3986 format). example: 'http://example.org/wiki/Main_Page' @@ -585,7 +580,7 @@ components: type: string description: not provided exists: - description: >- + description: | Indicator of whether the given allele was observed in the dataset. This should be non-null, unless there was an error, in which case `error` has to be non-null. @@ -617,7 +612,7 @@ components: description: Additional note or description of the response. externalUrl: type: string - description: >- + description: | URL to an external system, such as a secured beacon or a system providing more information about a given allele (RFC 3986 format). info: @@ -626,7 +621,7 @@ components: example: additionalInfoKey: additionalInfoValue BeaconError: - description: >- + description: | Beacon-specific error. This should be non-null in exceptional situations only, in which case `exists` has to be null. type: object From 224eb3a31a91efb90bad20d7117a2b3d215f2f11 Mon Sep 17 00:00:00 2001 From: Teemu Kataja Date: Fri, 18 Jan 2019 10:18:00 +0100 Subject: [PATCH 3/4] Update beacon.yaml Co-Authored-By: sdelatorrep --- beacon.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beacon.yaml b/beacon.yaml index 9e499138..5c62daab 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -166,7 +166,7 @@ paths: (datasetAlleleResponses) should be included in the response (BeaconAlleleResponse) to this request or not. - Use ERROR to filter out the datasets which return an error. + Use ERROR to return the datasets which return an error. If null (not specified), the default value of NONE is assumed. in: query From 3088c9caec8d011cc2bbd10adc53fff484cc5929 Mon Sep 17 00:00:00 2001 From: Teemu Kataja Date: Fri, 18 Jan 2019 10:18:09 +0100 Subject: [PATCH 4/4] Update beacon.yaml Co-Authored-By: sdelatorrep --- beacon.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beacon.yaml b/beacon.yaml index 5c62daab..1c015f0d 100644 --- a/beacon.yaml +++ b/beacon.yaml @@ -431,7 +431,7 @@ components: (datasetAlleleResponses) should be included in the response (BeaconAlleleResponse) to this request or not. - Use ERROR to filter out the datasets which return an error. + Use ERROR to return the datasets which return an error. If null (not specified), the default value of NONE is assumed. type: string