Commit c4a9f897 authored by Daniel Teixeira's avatar Daniel Teixeira
Browse files

adding beacon v3

parent 8e5cb19b
{
"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.",
"version": "0.3"
},
"schemes": [
"https"
],
"basePath": "/v03",
"produces": [
"application/json"
],
"paths": {
"/info": {
"get": {
"summary": "Beacon info endpoint",
"description": "Returns the information about this beacon (name, description, API version, URL, etc...)",
"responses": {
"200": {
"description": "A Beacon info page",
"schema": {
"$ref": "#/definitions/Beacon"
}
},
"default": {
"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.",
"parameters": [
{
"name": "chrom",
"in": "query",
"description": "Chromosome name. Accepted values are 1-22, X, Y and MT.",
"required": true,
"type": "string"
},
{
"name": "pos",
"in": "query",
"description": "Coordinate within a chromosome (0-based)",
"required": true,
"type": "number"
},
{
"name": "assembly",
"in": "query",
"description": "The version of the reference genome, NCBI notation.",
"required": true,
"type": "string"
},
{
"name": "alt",
"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.",
"required": true,
"type": "string"
},
{
"name": "ref",
"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.",
"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",
"required": false,
"type": "array",
"items": {
"type": "string"
}
}
],
"tags": [
"Query"
],
"responses": {
"200": {
"description": "A beacon allele response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/BeaconAlleleResponse"
}
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/BeaconError"
}
}
}
}
}
},
"definitions": {
"BeaconAlleleResponse": {
"type": "object",
"properties": {
"beaconId": {
"type": "string",
"description": "Beacon identfier"
},
"exists": {
"type": "boolean",
"description": "indicates whether the variant has been observed."
},
"alleleRequest": {
"type": "object",
"items": {
"$ref": "#/definitions/BeaconAlleleRequest"
},
"description": "The request to the Beacon."
},
"datasetAlleleResponses": {
"type": "array",
"description": "Datasets for which the variant is found.",
"items": {
"$ref": "#/definitions/DatasetAlleleResponse"
}
},
"errorInfo": {
"type": "object",
"items": {
"$ref": "#/definitions/BeaconError"
},
"description": "Error"
}
}
},
"BeaconAlleleRequest": {
"type": "object",
"properties": {
"chrom": {
"type": "string",
"description": "Chromosome name. Accepted values are 1-22, X, Y and MT."
},
"pos": {
"type": "number",
"description": "Coordinate within a chromosome (0-based)."
},
"assembly": {
"type": "string",
"description": "The version of the reference genome, NCBI notation."
},
"alt": {
"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": {
"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": {
"type": "array",
"items": {
"type": "string"
},
"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."
}
}
},
"BeaconError": {
"type": "object",
"properties": {
"status": {
"type": "number",
"description": "The error code."
},
"reason": {
"type": "string",
"description": "The reason of the error."
},
"message": {
"type": "string",
"description": "An error message."
}
}
},
"DatasetAlleleResponse": {
"type": "object",
"properties": {
"exists": {
"type": "boolean",
"description": "Can be used to indicate that this variant has been observed before and no other information."
},
"frequency": {
"type": "number",
"description": "Frequency of the allele in the dataset, 0.0-1.0, inclusive."
},
"errorInfo": {
"type": "array",
"items": {
"$ref": "#/definitions/BeaconError"
},
"description": "Beacon error."
},
"variantCount": {
"type": "number",
"description": "Number of variants in the dataset."
},
"callCount": {
"type": "number",
"description": "Number of called observations of this allele in the dataset."
},
"sampleCount": {
"type": "number",
"description": "Number of observations of this allele in the dataset."
},
"note": {
"type": "string",
"description": "Human-readable description of this variant."
},
"externalUrl": {
"type": "string",
"description": "URL with more information about a variant."
},
"info": {
"type": "array",
"items": {
"type": "string"
},
"description": "General information about the query."
}
}
},
"BeaconOrganization": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Short unique identifier for the organization hosting the beacon."
},
"name": {
"type": "string",
"description": "The organization name."
},
"description": {
"type": "string",
"description": "The organization description."
},
"address": {
"type": "string",
"description": "The address of the organization."
},
"welcomeUrl": {
"type": "string",
"description": "URL of homepage with additional info about the organizazion"
},
"contactUrl": {
"type": "string",
"description": "Beacon contact person in the organization."
},
"logoUrl": {
"type": "string",
"description": "URL with a logo shown."
},
"info": {
"type": "array",
"items": {
"type": "string"
},
"description": "General information about the organization."
}
}
},
"Beacon": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Short unique identifier for the beacon."
},
"organization": {
"$ref": "#/definitions/BeaconOrganization"
},
"description": {
"type": "string",
"description": "Longer human-readable description of the beacon."
},
"datasets": {
"type": "array",
"description": "List of datasets served by the beacon.",
"items": {
"$ref": "#/definitions/BeaconDataset"
}
},
"apiVersion": {
"type": "string",
"description": "Beacon API version."
},
"welcomeUrl": {
"type": "string",
"description": "URL of homepage with additional info about the beacon."
},
"sampleAlleleRequests": {
"type": "array",
"description": "Examples of allele requests.",
"items": {
"$ref": "#/definitions/BeaconAlleleRequest"
}
},
"name": {
"type": "string",
"description": "The beacon name."
},
"version": {
"type": "string",
"description": "The beacon version."
},
"alternativeUrl": {
"type": "string",
"description": "Alternative URL."
},
"created": {
"type": "number",
"description": "The beacon's creation date."
},
"updated": {
"type": "number",
"description": "The beacon's last update date."
},
"info": {
"description": "General information about the beacon.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"BeaconDataset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Short unique identifier for the dataset."
},
"assembly": {
"type": "string",
"description": "The version of the reference genome, NCBI notation."
},
"description": {
"type": "string",
"description": "The dataset's description."
},
"dataUse": {
"$ref": "#/definitions/DataUse"
},
"name": {
"type": "string",
"description": "The dataset's name."
},
"created": {
"type": "number",
"description": "The dataset creation date."
},
"updated": {
"type": "number",
"description": "The dataset's last update date."
},
"version": {
"type": "string",
"description": "The version of the dataset."
},
"variantCount": {
"type": "number",
"description": "The number of variants in the dataset."
},
"callCount": {
"type": "number",
"description": "The number of calls in the dataset."
},
"sampleCount": {
"type": "number",
"description": "The number of samples in the dataset."
},
"externalUrl": {
"type": "string",
"description": "The URL of a page with additional info about the dataset."
},
"info": {
"description": "General inoformation about the dataset.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"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
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment