Commit 94103b7e authored by Severine Duvaud's avatar Severine Duvaud
Browse files

Updated param names + Removal of DataUseConscent

parent 442c0601
......@@ -39,47 +39,47 @@
"/query": {
"get": {
"summary": "Beacon query endpoint",
"description": "To actually ask the beacon for questions like \"do you have any genomes with an 'A' at position 100,735 on chromosome 3?\" And the answer will be yes or no.",
"description": "To actually ask the beacon for questions like \\\"do you have any genomes with an \"A\" at position 100,735 on chromosome 3?\\\" And the answer will be yes or no.",
"parameters": [
{
"name": "chrom",
"name": "referenceName",
"in": "query",
"description": "Chromosome name. Accepted values are 1-22, X, Y and MT.",
"required": true,
"type": "string"
},
{
"name": "pos",
"name": "start",
"in": "query",
"description": "Coordinate within a chromosome (0-based)",
"description": "Position, allele locus (0-based). Accepted values: non-negative integers smaller than reference length.",
"required": true,
"type": "number"
},
{
"name": "assembly",
"name": "assemblyId",
"in": "query",
"description": "The version of the reference genome, NCBI notation.",
"required": true,
"type": "string"
},
{
"name": "alt",
"name": "alternateBases",
"in": "query",
"description": "The bases that appear instead of the reference bases. The semantics correspond to the field ALT in VCF. Options are base Strings made up of A,C,G,T,N,* (case insensitive) or an angle-bracketed ID or a breakend replacement string.",
"description": "The bases that appear instead of the reference bases. Accepted values: see the ALT field in VCF 4.2 specification.",
"required": true,
"type": "string"
},
{
"name": "ref",
"name": "referenceBases",
"in": "query",
"description": "The reference bases for this variant, starting from `position`, in the genome described by the field `reference`. The semantics correspond to the field REF in VCF. One of A,C,G,T,N (case insensitive). Multiple bases are permitted.",
"description": "Reference bases for this variant (starting from `start`). Accepted values: see the REF field in VCF 4.2 specification.",
"required": true,
"type": "string"
},
{
"name": "datasetIds",
"in": "query",
"description": "Limit to a set of datasetIds at the target website. An ID is specific to the website that is queried and can be an accession ID, population or any other identifier",
"description": "Limit to a set of datasetIds at the target website. An ID is specific to the website that is queried and can be an accession ID, population or any other identifier.",
"required": false,
"type": "array",
"items": {
......@@ -116,11 +116,11 @@
"properties": {
"beaconId": {
"type": "string",
"description": "Beacon identfier"
"description": "Identifier of the beacon, as defined in `Beacon`."
},
"exists": {
"type": "boolean",
"description": "indicates whether the variant has been observed."
"description": "Indicates whether the variant has been observed. Might be removed in the future."
},
"alleleRequest": {
"type": "object",
......@@ -131,40 +131,40 @@
},
"datasetAlleleResponses": {
"type": "array",
"description": "Datasets for which the variant is found.",
"description": "Indicator of whether the beacon has observed the allele.",
"items": {
"$ref": "#/definitions/DatasetAlleleResponse"
"$ref": "#/definitions/BeaconDatasetAlleleResponse"
}
},
"errorInfo": {
"error": {
"type": "object",
"items": {
"$ref": "#/definitions/BeaconError"
},
"description": "Error"
"description": "Beacon-specific error. This should be non-null in exceptional situations only."
}
}
},
"BeaconAlleleRequest": {
"type": "object",
"properties": {
"chrom": {
"referenceName": {
"type": "string",
"description": "Chromosome name. Accepted values are 1-22, X, Y and MT."
},
"pos": {
"start": {
"type": "number",
"description": "Coordinate within a chromosome (0-based)."
},
"assembly": {
"assemblyId": {
"type": "string",
"description": "The version of the reference genome, NCBI notation."
},
"alt": {
"alternateBases": {
"type": "string",
"description": "The bases that appear instead of the reference bases. The semantics correspond to the field ALT in VCF. Options are base Strings made up of A,C,G,T,N,* (case insensitive) or an angle-bracketed ID or a breakend replacement string."
},
"ref": {
"referenceBases": {
"type": "string",
"description": "The reference bases for this variant, starting from `position`, in the genome described by the field `reference`. The semantics correspond to the field REF in VCF. One of A,C,G,T,N (case insensitive). Multiple bases are permitted."
},
......@@ -180,37 +180,37 @@
"BeaconError": {
"type": "object",
"properties": {
"status": {
"errorCode": {
"type": "number",
"description": "The error code."
},
"reason": {
"type": "string",
"description": "The reason of the error."
},
"message": {
"type": "string",
"description": "An error message."
}
}
},
"DatasetAlleleResponse": {
"BeaconDatasetAlleleResponse": {
"type": "object",
"properties": {
"datasetId": {
"type": "string",
"description": "Identifier of the dataset, as defined in `BeaconDataset`."
},
"exists": {
"type": "boolean",
"description": "Can be used to indicate that this variant has been observed before and no other information."
"description": "Indicator of whether the given allele was observed in the dataset. This should be non-null, unless there was an error."
},
"frequency": {
"type": "number",
"description": "Frequency of the allele in the dataset, 0.0-1.0, inclusive."
},
"errorInfo": {
"error": {
"type": "array",
"items": {
"$ref": "#/definitions/BeaconError"
},
"description": "Beacon error."
"description": "Dataset-specific error. This should be non-null in exceptional situations only, in which case `exists` has to be null."
},
"variantCount": {
"type": "number",
......@@ -262,7 +262,7 @@
},
"welcomeUrl": {
"type": "string",
"description": "URL of homepage with additional info about the organizazion"
"description": "URL of homepage with additional info about the organization"
},
"contactUrl": {
"type": "string",
......@@ -308,7 +308,7 @@
},
"welcomeUrl": {
"type": "string",
"description": "URL of homepage with additional info about the beacon."
"description": "URL of homepage with additional info about the Beacon."
},
"sampleAlleleRequests": {
"type": "array",
......@@ -319,11 +319,11 @@
},
"name": {
"type": "string",
"description": "The beacon name."
"description": "The Beacon name."
},
"version": {
"type": "string",
"description": "The beacon version."
"description": "The Beacon version."
},
"alternativeUrl": {
"type": "string",
......@@ -331,14 +331,14 @@
},
"created": {
"type": "number",
"description": "The beacon's creation date."
"description": "The Beacon creation date."
},
"updated": {
"type": "number",
"description": "The beacon's last update date."
"description": "The Beacon last update date."
},
"info": {
"description": "General information about the beacon.",
"description": "General information about the Beacon.",
"type": "array",
"items": {
"type": "string"
......@@ -353,20 +353,21 @@
"type": "string",
"description": "Short unique identifier for the dataset."
},
"assembly": {
"assemblyId": {
"type": "string",
"description": "The version of the reference genome, NCBI notation."
"description": "Assembly identifier (GRC notation, e.g. `GRCh37`). Why not \"referenceName\"?"
},
"description": {
"type": "string",
"description": "The dataset's description."
"description": "The dataset description."
},
"dataUse": {
"$ref": "#/definitions/DataUse"
"consentCodeDataUse": {
"type": "string",
"description": "Should be org.ga4gh.consentcode.ConsentCodeDataUse and not string."
},
"name": {
"type": "string",
"description": "The dataset's name."
"description": "The dataset name."
},
"created": {
"type": "number",
......@@ -374,7 +375,7 @@
},
"updated": {
"type": "number",
"description": "The dataset's last update date."
"description": "The dataset last update date."
},
"version": {
"type": "string",
......@@ -404,41 +405,6 @@
}
}
}
},
"DataUse": {
"type": "object",
"properties": {
"primaryCategory": {
"$ref": "#/definitions/DataUseCondition"
},
"requirements": {
"description": "List of data use requirements.",
"type": "array",
"items": {
"$ref": "#/definitions/DataUseCondition"
}
},
"secondaryCategories": {
"description": "List of secondary data use conditions.",
"type": "array",
"items": {
"$ref": "#/definitions/DataUseCondition"
}
}
}
},
"DataUseCondition": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Data use condition description."
},
"code": {
"type": "string",
"description": "Data use condition code."
}
}
}
}
}
\ No newline at end of file
swagger: '2.0'
info:
title: Beacon API
description: This document represents a proposal for the next version of the API for the GA4GH Beacon Project. The new API is intended to expose new functionalities motivated by potential uses cases contributed by the community.
description: 'This document represents a proposal for the next version of the API for the GA4GH Beacon Project. The new API is intended to expose new functionalities motivated by potential uses cases contributed by the community.'
version: '0.3'
schemes:
- https
......@@ -11,52 +11,52 @@ produces:
paths:
/info:
get:
summary: Beacon info endpoint
summary: 'Beacon info endpoint'
description: 'Returns the information about this beacon (name, description, API version, URL, etc...)'
responses:
'200':
description: A Beacon info page
description: 'A Beacon info page'
schema:
$ref: '#/definitions/Beacon'
default:
description: Unexpected error
description: 'Unexpected error'
schema:
$ref: '#/definitions/BeaconError'
tags:
- Info
/query:
get:
summary: Beacon query endpoint
description: "To actually ask the beacon for questions like \"do you have any genomes with an 'A' at position 100,735 on chromosome 3?\" And the answer will be yes or no."
summary: 'Beacon query endpoint'
description: 'To actually ask the beacon for questions like \"do you have any genomes with an "A" at position 100,735 on chromosome 3?\" And the answer will be yes or no.'
parameters:
- name: chrom
- name: referenceName
in: query
description: 'Chromosome name. Accepted values are 1-22, X, Y and MT.'
required: true
type: string
- name: pos
- name: start
in: query
description: Coordinate within a chromosome (0-based)
description: 'Position, allele locus (0-based). Accepted values: non-negative integers smaller than reference length.'
required: true
type: number
- name: assembly
- name: assemblyId
in: query
description: 'The version of the reference genome, NCBI notation.'
required: true
type: string
- name: alt
- name: alternateBases
in: query
description: 'The bases that appear instead of the reference bases. The semantics correspond to the field ALT in VCF. Options are base Strings made up of A,C,G,T,N,* (case insensitive) or an angle-bracketed ID or a breakend replacement string.'
description: 'The bases that appear instead of the reference bases. Accepted values: see the ALT field in VCF 4.2 specification.'
required: true
type: string
- name: ref
- name: referenceBases
in: query
description: 'The reference bases for this variant, starting from `position`, in the genome described by the field `reference`. The semantics correspond to the field REF in VCF. One of A,C,G,T,N (case insensitive). Multiple bases are permitted.'
description: 'Reference bases for this variant (starting from `start`). Accepted values: see the REF field in VCF 4.2 specification.'
required: true
type: string
- name: datasetIds
in: query
description: 'Limit to a set of datasetIds at the target website. An ID is specific to the website that is queried and can be an accession ID, population or any other identifier'
description: 'Limit to a set of datasetIds at the target website. An ID is specific to the website that is queried and can be an accession ID, population or any other identifier.'
required: false
type: array
items:
......@@ -65,13 +65,13 @@ paths:
- Query
responses:
'200':
description: A beacon allele response
description: 'A beacon allele response'
schema:
type: array
items:
$ref: '#/definitions/BeaconAlleleResponse'
default:
description: Unexpected error
description: 'Unexpected error'
schema:
$ref: '#/definitions/BeaconError'
definitions:
......@@ -80,41 +80,41 @@ definitions:
properties:
beaconId:
type: string
description: Beacon identfier
description: 'Identifier of the beacon, as defined in `Beacon`.'
exists:
type: boolean
description: indicates whether the variant has been observed.
description: 'Indicates whether the variant has been observed. Might be removed in the future.'
alleleRequest:
type: object
items:
$ref: '#/definitions/BeaconAlleleRequest'
description: The request to the Beacon.
description: 'The request to the Beacon.'
datasetAlleleResponses:
type: array
description: Datasets for which the variant is found.
description: 'Indicator of whether the beacon has observed the allele.'
items:
$ref: '#/definitions/DatasetAlleleResponse'
errorInfo:
$ref: '#/definitions/BeaconDatasetAlleleResponse'
error:
type: object
items:
$ref: '#/definitions/BeaconError'
description: Error
description: 'Beacon-specific error. This should be non-null in exceptional situations only.'
BeaconAlleleRequest:
type: object
properties:
chrom:
referenceName:
type: string
description: 'Chromosome name. Accepted values are 1-22, X, Y and MT.'
pos:
start:
type: number
description: Coordinate within a chromosome (0-based).
assembly:
description: 'Coordinate within a chromosome (0-based).'
assemblyId:
type: string
description: 'The version of the reference genome, NCBI notation.'
alt:
alternateBases:
type: string
description: 'The bases that appear instead of the reference bases. The semantics correspond to the field ALT in VCF. Options are base Strings made up of A,C,G,T,N,* (case insensitive) or an angle-bracketed ID or a breakend replacement string.'
ref:
referenceBases:
type: string
description: 'The reference bases for this variant, starting from `position`, in the genome described by the field `reference`. The semantics correspond to the field REF in VCF. One of A,C,G,T,N (case insensitive). Multiple bases are permitted.'
datasetIds:
......@@ -125,122 +125,122 @@ definitions:
BeaconError:
type: object
properties:
status:
errorCode:
type: number
description: The error code.
reason:
type: string
description: The reason of the error.
description: 'The error code.'
message:
type: string
description: An error message.
DatasetAlleleResponse:
description: 'An error message.'
BeaconDatasetAlleleResponse:
type: object
properties:
datasetId:
type: string
description: 'Identifier of the dataset, as defined in `BeaconDataset`.'
exists:
type: boolean
description: Can be used to indicate that this variant has been observed before and no other information.
description: 'Indicator of whether the given allele was observed in the dataset. This should be non-null, unless there was an error.'
frequency:
type: number
description: 'Frequency of the allele in the dataset, 0.0-1.0, inclusive.'
errorInfo:
error:
type: array
items:
$ref: '#/definitions/BeaconError'
description: Beacon error.
description: 'Dataset-specific error. This should be non-null in exceptional situations only, in which case `exists` has to be null.'
variantCount:
type: number
description: Number of variants in the dataset.
description: 'Number of variants in the dataset.'
callCount:
type: number
description: Number of called observations of this allele in the dataset.
description: 'Number of called observations of this allele in the dataset.'
sampleCount:
type: number
description: Number of observations of this allele in the dataset.
description: 'Number of observations of this allele in the dataset.'
note:
type: string
description: Human-readable description of this variant.
description: 'Human-readable description of this variant.'
externalUrl:
type: string
description: URL with more information about a variant.
description: 'URL with more information about a variant.'
info:
type: array
items:
type: string
description: General information about the query.
description: 'General information about the query.'
BeaconOrganization:
type: object
properties:
id:
type: string
description: Short unique identifier for the organization hosting the beacon.
description: 'Short unique identifier for the organization hosting the beacon.'
name:
type: string
description: The organization name.
description: 'The organization name.'
description:
type: string
description: The organization description.
description: 'The organization description.'
address:
type: string
description: The address of the organization.
description: 'The address of the organization.'
welcomeUrl:
type: string
description: URL of homepage with additional info about the organizazion
description: 'URL of homepage with additional info about the organization'
contactUrl:
type: string
description: Beacon contact person in the organization.
description: 'Beacon contact person in the organization.'
logoUrl:
type: string
description: URL with a logo shown.
description: 'URL with a logo shown.'
info:
type: array
items:
type: string
description: General information about the organization.
description: 'General information about the organization.'
Beacon:
type: object
properties:
id:
type: string
description: Short unique identifier for the beacon.
description: 'Short unique identifier for the beacon.'
organization:
$ref: '#/definitions/BeaconOrganization'
description:
type: string
description: Longer human-readable description of the beacon.
description: 'Longer human-readable description of the beacon.'
datasets:
type: array
description: List of datasets served by the beacon.
description: 'List of datasets served by the beacon.'
items:
$ref: '#/definitions/BeaconDataset'
apiVersion:
type: string
description: Beacon API version.
description: 'Beacon API version.'
welcomeUrl:
type: string
description: URL of homepage with additional info about the beacon.
description: 'URL of homepage with additional info about the Beacon.'
sampleAlleleRequests:
type: array
description: Examples of allele requests.
description: 'Examples of allele requests.'
items:
$ref: '#/definitions/BeaconAlleleRequest'
name:
type: string
description: The beacon name.
description: 'The Beacon name.'
version:
type: string
description: The beacon version.
description: 'The Beacon version.'
alternativeUrl:
type: string
description: Alternative URL.
description: 'Alternative URL.'
created:
type: number
description: "The beacon's creation date."
description: 'The Beacon creation date.'
updated:
type: number
description: "The beacon's last update date."