├── doc └── source │ └── _static │ ├── 2017-05-03_range_example_slide_Michael_Baudis.pdf │ └── 2017-05-03_range_example_slide_Michael_Baudis.png ├── .gitignore ├── .travis.yml ├── README.md ├── CONTRIBUTING.md ├── LICENSE ├── beacon.md └── beacon.yaml /doc/source/_static/2017-05-03_range_example_slide_Michael_Baudis.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ga4gh-beacon/specification/HEAD/doc/source/_static/2017-05-03_range_example_slide_Michael_Baudis.pdf -------------------------------------------------------------------------------- /doc/source/_static/2017-05-03_range_example_slide_Michael_Baudis.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ga4gh-beacon/specification/HEAD/doc/source/_static/2017-05-03_range_example_slide_Michael_Baudis.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | #********** windows template********** 2 | 3 | # Windows image file caches 4 | Thumbs.db 5 | 6 | # Folder config file 7 | Desktop.ini 8 | 9 | # Recycle Bin used on file shares 10 | $RECYCLE.BIN/ 11 | 12 | 13 | #********** osx template********** 14 | 15 | .DS_Store 16 | 17 | # Thumbnails 18 | ._* 19 | 20 | # Files that might appear on external disk 21 | .Spotlight-V100 22 | .Trashes 23 | 24 | 25 | #********** linux template********** 26 | 27 | .* 28 | !.gitignore 29 | *~ 30 | 31 | # KDE 32 | .directory 33 | 34 | 35 | #********** emacs template********** 36 | 37 | \#*\# 38 | /.emacs.desktop 39 | /.emacs.desktop.lock 40 | .elc 41 | auto-save-list 42 | tramp 43 | .\#* 44 | 45 | # Org-mode 46 | .org-id-locations 47 | *_archive 48 | 49 | 50 | #********** vim template********** 51 | 52 | .*.sw[a-z] 53 | *.un~ 54 | Session.vim 55 | 56 | 57 | #********** Travis CI ********** 58 | 59 | !.travis.yml 60 | 61 | #********** IntelliJ files ****** 62 | *.iml 63 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: java 2 | dist: trusty 3 | sudo: false 4 | jdk: 5 | - oraclejdk8 6 | env: 7 | - GH_URL=https://raw.githubusercontent.com VALIDATOR_URL=http://localhost:8080/api/debug?url FILE_TO_VALIDATE=beacon.yaml URL_TO_VALIDATE=$GH_URL/$TRAVIS_REPO_SLUG/${TRAVIS_PULL_REQUEST_BRANCH:-$TRAVIS_BRANCH}/$FILE_TO_VALIDATE 8 | before_install: 9 | # This setup will not be needed once the online version of validator-badge supports OAS 3.0. Until then we'll need to set up a local version. Since there isn't a release supporting OAS 3.0 yet, we unfortunately need to build some snapshot dependencies. These steps should be gradually removed as releases come out. 10 | 11 | # build swagger-core 12 | - git clone --branch=v2.0.2 https://github.com/swagger-api/swagger-core.git 13 | - cd swagger-core 14 | - git reset --hard 5336adb9945cfdf6eddbb61f15b28a1509e0b267 15 | - mvn install -DskipTests=true -Dmaven.javadoc.skip=true -B -V 16 | - cd .. 17 | 18 | # build swagger-parser 19 | - git clone --branch=v2.0.0 https://github.com/swagger-api/swagger-parser.git 20 | - cd swagger-parser 21 | - git reset --hard 7ce0f756364acee3262444ab998e9fe0963382b3 22 | - mvn install -DskipTests=true -Dmaven.javadoc.skip=true -B -V 23 | - cd .. 24 | 25 | # build swagger-inflector 26 | - git clone --branch=v1.0.16 https://github.com/swagger-api/swagger-inflector.git 27 | - cd swagger-inflector 28 | - git reset --hard 421fedb162b9e9b781671bc7757ee78eb6d1f793 29 | - mvn install -DskipTests=true -Dmaven.javadoc.skip=true -B -V 30 | - cd .. 31 | 32 | # build and start validator-badge 33 | - git clone --branch=2.0 https://github.com/swagger-api/validator-badge.git 34 | - cd validator-badge 35 | - mvn package -DskipTests=true -Dmaven.javadoc.skip=true -B -V jetty:run & 36 | - cd .. 37 | - sleep 60 38 | script: 39 | # validate 40 | - echo "Validating $URL_TO_VALIDATE:" 41 | - VALIDATION_OUTPUT=`curl -sS "$VALIDATOR_URL=$URL_TO_VALIDATE"` 42 | 43 | # print validation errors 44 | - echo $VALIDATION_OUTPUT 45 | 46 | # check if the validation output is an empty array, i.e. no errors 47 | - test "$VALIDATION_OUTPUT" == "[]" 48 | notifications: 49 | slack: 50 | secure: RmyIMB6tA868r+dHECJ566r0+TCB6pHvg9PygNiM5ye+iX4I+CFKMoGzjeMVtuLI80MSzzoaB+PU6TczlhzdbJBALqiV74AQCoNGqswJzJCkJX7HDGk8LVFSsnpwClRLLLVgvBApGDS0ViRfGqsew8CJ8VR5BMDiU53z3Of4JHc= 51 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ARCHIVE: Beacon v1 2 | 3 | The Beacon v1 specification has not been updated since 2020 and has been replaced with the Beacon v2 specification, officially approved in Spring 2022. Please see the [documentation site](http://docs.genomebeacons.org) and the [code repository](http://github.com/ga4gh-beacon/beacon-v2/). 4 | 5 | The implementation of "v1" type beacons is now discouraged; beacons can be configured in v2 with v1-like functionality. 6 | 7 | ---- 8 | 9 | # ~~Beacon API specification [![](https://img.shields.io/badge/license-Apache%202-blue.svg)](https://raw.githubusercontent.com/ga4gh-beacon/specification/develop/LICENSE)~~ 10 | 11 | ## What is a Beacon? 12 | 13 | The Beacon protocol defines an open standard for genomics data discovery, developed by members of the Global Alliance for Genomics & Health. It provides a framework for public web services responding to queries against genomic data collections, for instance from population based or disease specific genome repositories. 14 | 15 | The Beacon protocol has been designed to be: 16 | 17 | * Simple: focus on robustness and easy implementation 18 | * Federated: maintained by individual organizations and assembled into a network 19 | * General-purpose: used to report on any variant collection 20 | * Aggregative: provide a boolean (or quantitative) answer about the observation of a variant 21 | * Privacy protecting: queries do not return information about single individuals 22 | 23 | The main places to find information about the Beracon project are: 24 | 25 | * Beacon project [website](https://beacon-project.io) 26 | * short documentation about the specification [in this repository](./beacon.md) 27 | * [wiki](https://github.com/ga4gh-beacon/specification/wiki) (outdated) 28 | 29 | 30 | ## Specification 31 | 32 | The specification is done in [OpenAPI format](beacon.yaml) and it is online in [Swagger Hub](https://app.swaggerhub.com/apis/ELIXIR-Finland/ga-4_gh_beacon_api_specification/1.0.0-rc1). The overall design is explained in the [beacon.md](beacon.md) document. 33 | 34 | ## License 35 | 36 | This project is licensed under the terms of the [Apache2.0 license](LICENSE). 37 | 38 | ## How to contribute 39 | 40 | Guidelines for contributing to this repository are listed in the [CONTRIBUTING.md](CONTRIBUTING.md) document. To introduce new development ideas or enhancements please use [this wiki-page](https://github.com/ga4gh-beacon/specification/wiki/Future-enhancements-and-development-ideas). 41 | 42 | ## How to test 43 | 44 | Use [Swagger Validator Badge](https://github.com/swagger-api/validator-badge) to validate the YAML file. 45 | 46 | ## Communications 47 | - [Slack Channel](https://beacon-team-slackin.herokuapp.com/) 48 | 49 | ## GitHub projects page 50 | 51 | All members of the [ga4gh-beacon GitHub organisation](https://github.com/ga4gh-beacon) have access to the [projects page](https://github.com/orgs/ga4gh-beacon/projects/1). 52 | 53 | This page is used to plan and manage the work across the ga4gh-beacon repositories, allowing everyone to see what’s already in motion and to work together without duplicating effort. 54 | 55 | ## Notify GA4GH of potential security flaw in specification 56 | 57 | To enable a long-term contact for potential security flaws an email address of security-notification@ga4gh.org has been set up. This email will be monitored by the GA4GH secretariat and GA4GH security members to allow for an incoming response to be directed to appropriate parties.~~ 58 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to contribute 2 | 3 | Thank you for taking the time to contribute. We appreciate it! 4 | 5 | There are two ways to contribute - via issues, which are used for discussion, and pull requests, which are concrete proposals of change. 6 | 7 | ## Issues 8 | 9 | The project's [Issues Page](https://github.com/ga4gh-beacon/specification/issues) is a forum to discuss both major and minor issues related to developing the Beacon API. It also serves as the means for collaborating with the group and discussing contributions that will ultimately lead to changes to the API. See the [Issue](#issue_resolution) section below for specifics on how issues are resolved by the community. 10 | 11 | ## Pull Requests 12 | 13 | The way to contribute development effort and code to the project is via GitHub pull requests. GitHub provides a nice [overview on how to create a pull request](https://help.github.com/articles/creating-a-pull-request). Pull Requests should usually be made against the [`develop` branch](https://github.com/ga4gh-beacon/specification/tree/develop). 14 | 15 | Some general rules to follow: 16 | 17 | - Create a branch for each update that you're working on. These branches are often called "feature" or "topic" branches. Any changes that you push to your feature branch will automatically be shown in the pull request. 18 | - Keep your pull requests as small as possible. Large pull requests are hard to review. Try to break up your changes into self-contained and incremental pull requests. 19 | - The first line of commit messages should be a short (<80 character) summary, followed by an empty line and then any details that you want to share about the commit. 20 | - Please try to follow the [existing syntax style](#syntax_style). 21 | 22 | ## Issue Resolution 23 | 24 | Once a pull request or issue have been submitted, anyone can comment or vote on to express their opinion following the Apache voting system. Quick summary: 25 | 26 | - **+1** something you agree with 27 | - **-1** if you have a strong objection to an issue, which will be taken very seriously. A -1 vote should provide an alternative solution. 28 | - **+0** or **-0** for neutral comments or weak opinions. 29 | - It's okay to have input without voting. 30 | - Silence gives assent. 31 | 32 | A pull request is ready to be merged when either of the following is true: 33 | - A pull request has at least two **+1** votes, no **-1** votes, and has been open for at least 3 days. 34 | - A pull request has no **-1** votes, and has been open for at least 14 days. 35 | 36 | We sometimes waive the time constraint for cosmetic-only changes -- use good judgment. If an issue gets any **-1** votes, the comments on the issue need to reach consensus before the issue can be resolved one way or the other. There isn't any strict time limit on a contentious issue. 37 | 38 | The project will strive for full consensus on everything until it runs into a problem with this model. 39 | 40 | ## Gitflow Workflow 41 | 42 | Our workflow is based on [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow), which defines a strict branching model designed around the project release. This workflow uses two branches to record the history of the project. The master branch stores the official release history, and the develop branch serves as an integration branch for features. Aside from these two main branches, the workflow utilizes topic and release branches. 43 | 44 | ### Topic Branches 45 | 46 | If you wish to collaborate on a new feature with other GA4GH members you can ask that a topic branch be created. Since Github does not allow pull requests against branches that do not yet exist, you will have to create an issue asking for the topic branch to be created. 47 | 48 | Once a topic branch exists, pull requests can be made against it in the usual way. It may also be brought up to date with new changes merged into develop by anyone with commit access, if the changes produce merely a fast-forward merge for each constituent branch. However, if changes from the develop branch create a new merge commit in or or more of the repositories, that commit needs to be reviewed in a pull request. 49 | 50 | Changes made in a topic branch can be merged into develop by creating and then resolving in the normal way a pull request against the develop branch. 51 | 52 | Topic branches that have been merged into develop and that are no longer being developed upon should be [deleted](https://github.com/blog/1335-tidying-up-after-pull-requests) (they will still appear in the git history). 53 | 54 | ### Release Branches 55 | 56 | From time to time the group will make a release. This is achieved by creating a branch named "release-foo", where foo is the release name. Only bug fixes are allowed to release branches. To refer to a specific version of a release branch either the commit id can be used, or alternatively (better), a tag can be created (which should be replicated across repositories). 57 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright 2018 ELIXIR Beacon Project 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | 203 | -------------------------------------------------------------------------------- /beacon.md: -------------------------------------------------------------------------------- 1 | 2 | # Beacon API Specification v1.0.0 3 | 4 | Beacon is a web service for genetic data sharing. Beacon permits simple queries regarding the presence or absence of a specified variant in a given dataset. This is the key idea behind Beacon, by allowing these queries Beacon makes the data discoverable. If the user finds their variant(s) of interest, Beacon will point them to the appropriate place to gain access to the data (e.g. the European Genome-Phenome Archive, EGA). 5 | 6 | **Authors**: _Ilkka Lappalainen, Jordi Rambla, Juha Törnroos, Kasper Keinänen, Marc Fiume, Michael Baudis, Miro Cupack, Sabela de la Torre, Saif Ur-Rehman_ 7 | 8 | 9 | ## Design Principles 10 | The Beacon protocol provides _query interface_ that has been designed to be: 11 | 12 | - **Simple:** focuses on robustness and easy implementation 13 | - **Federated:** maintained by individual organizations and assembled into a network 14 | - **General-purpose:** used to distribute any allelic dataset 15 | - **Aggregative:** provides a boolean answer to whether an allele was observed 16 | - **Privacy protecting:** queries do not return information about single individuals 17 | 18 | 19 | Due to the needs for data discoverability providing as much metadata as possible in query responses is endorsed. The Beacon is limited for human data only. 20 | 21 | 22 | ## Protocol essentials 23 | 24 | Beacon provides REST API on top of the HTTPS protocol, as specified in RFC 7231. HTTPS (HTTP over SSL) SHOULD be used instead of regular HTTP because the communication between Beacon server and Beacon client has to be encrypted. The Beacon API has two endpoints: `/` (also known as _Info endpoint_) and `/query`. The _Info endpoint_ provides general metadata about the Beacon instance and dataset(s) included. The query interface is provided by the _Query endpoint_. 25 | 26 | The full complement of Beacon API endpoints, requests and responses is published in [OpenAPI format](https://github.com/ga4gh-beacon/specification/blob/master/beacon.yaml). 27 | 28 | ### Security 29 | Beacon endorses GA4GH's 3-tier access to data: 30 | 31 | - **Open:** No authentication (verification of identity) or authorization (verification of access rights). 32 | 33 | - **Registered:** Authentication of the user is performed. For example it is required that the user is `bona-fide researcher`. 34 | 35 | - **Controlled:** Both authentication and authorization checks are performed to ensure that the user has been granted to access the data they are querying. 36 | 37 | Registered and controlled access requires authentication of the user. The Beacon API supports authenticated queries using OAuth2 Bearer tokens in HTTP Authorisation header as specified in [RFC 6750](https://tools.ietf.org/html/rfc6750): 38 | 39 | GET /query HTTP/1.1 40 | Host: beacon.com 41 | Authorization: Bearer doPk34akbm9bsw5nknklex 42 | 43 | Both granting access to the data and identifying `bona-fide researchers` **is not** Beacon's responsibility. 44 | 45 | ### Errors 46 | 47 | The server MUST respond with the appropriate HTTP status code when an error condition is detected. In the case of transient 48 | server errors, (e.g., 500 and other 5xx status codes), the client SHOULD implement appropriate retry logic. 49 | 50 | For errors that are specific to the Beacon API, the response will be one of the HTTP status codes represented in the table below. 51 | The response body SHOULD be a JSON object (`Content-Type: application/json`) providing machine-readable information 52 | about the nature of the error, along with a human-readable description. 53 | 54 | 55 | The following error types are defined: 56 | 57 | | Error type | HTTP status code | Description | 58 | |---|:---:|---| 59 | |Bad request|400|Mandatory parameters are missing or they are invalid| 60 | |Unauthorized|401|An unauthenticated user is trying to access a protected resource| 61 | |Forbidden|403|The resource is protected for all users, or the user is authenticated but they are not granted access for this resource| 62 | 63 | The error type SHOULD be chosen from this table and be accompanied by the specified HTTP status code. 64 | An example of a valid JSON error response is: 65 | 66 | ```json 67 | "error": { 68 | "errorCode": 400, 69 | "errorMessage": "Missing mandatory parameter referenceName" 70 | } 71 | ``` 72 | 73 | ### CORS 74 | Beacon API SHOULD support cross-origin resource sharing (CORS) and follow [GA4GH CORS recommendations](https://docs.google.com/document/d/1Ifiik9afTO-CEpWGKEZ5TlixQ6tiKcvug4XLd9GNcqo/edit). 75 | 76 | 77 | ### External Standards referenced in the API 78 | - The Automatable Discovery and Access Matrix ([ADAM](https://github.com/ga4gh/ADA-M)) 79 | - GA4GH Consent Codes ([GA4GH-CC](https://github.com/ga4gh/ga4gh-consent-policy)) 80 | 81 | ## Info endpoint 82 | 83 | ### Request 84 | ##### - URL: `/` 85 | ##### - HTTP method: `GET` 86 | ##### - Parameters: `None` 87 | 88 | ### Response 89 | ##### Content-type:`application/json` 90 | ##### Payload: `Beacon object` 91 | 92 | **Beacon object** 93 | 94 | |Properties (* mandatory, ~ one of these is mandatory)|Description|Type|Example| 95 | |---|---|:---:|---| 96 | |*id* *|Unique identifier of the beacon. Use reverse domain name notation.|string|org.ga4gh.beacon| 97 | |*name* *|Human readable name of the beacon|string|EGA Beacon| 98 | |*apiVersion* *|Version of the API provided by the beacon.|string|v1.0.0| 99 | |*organisation* *|Organisation providing the Beacon|object|Beacon Organisation object (see below)| 100 | |*datasets* *|Datasets served by the beacon. Any beacon should specify at least one dataset.|array|Array of Beacon Dataset objects (see below)| 101 | |description|Description of the beacon.|string|"This sample set comprises cases of schizophrenia with additional cognitive measurements, collected in Aberdeen, Scotland."| 102 | |version|Version of the Beacon server instance.|string|v0.1| 103 | |welcomeUrl|URL to the welcome page for this beacon (RFC 3986 format).|string|'http://example.org/wiki/Main_Page'| 104 | |alternativeUrl|Alternative URL to the API, e.g. a restricted version of this beacon (RFC 3986 format).|string|'http://example.org/wiki/Main_Page'| 105 | |createDateTime|The time the beacon was created (ISO 8601 format).|string|'2012-07-19 or 2017-01-17T20:33:40Z'| 106 | |updateDateTime|The time the beacon was updated in (ISO 8601 format).|string|'2012-07-19 or 2017-01-17T20:33:40Z'| 107 | |sampleAlleleRequests|Examples of interesting queries, e.g. a few queries demonstrating different responses.|array|Array of BeaconAlleleRequest objects (see _Query endpoint request_)| 108 | |info|'Additional structured metadata, key-value pairs.'|array|-| 109 | 110 | **Beacon Organisation object** 111 | 112 | |Properties (* mandatory, ~ one of these is mandatory)|Description|Type|Example| 113 | |---|---|:---:|---| 114 | |*id**|Unique identifier of the organization.|string|-| 115 | |*name**|Name of the organization.|string|-| 116 | |description|Description of the organization.|string|-| 117 | |address|Address of the organization.|string|-| 118 | |welcomeUrl|URL of the website of the organization (RFC 3986 format).|string|-| 119 | |contactUrl|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).|string|-| 120 | |logoUrl|URL to the logo (PNG/JPG format) of the organization (RFC 3986 format).|string|-| 121 | |info|Additional structured metadata, key-value pairs.|string|-| 122 | 123 | **Beacon Dataset object** 124 | 125 | |Properties (* mandatory, ~ one of these is mandatory)|Description|Type|Example| 126 | |---|---|:---:|---| 127 | |*id**|Unique identifier of the dataset.|string|-| 128 | |*name**|Name of the dataset.|string|-| 129 | |*assemblyId**|Assembly identifier|string|`'GRCh38'`| 130 | |*createDateTime**|The time the dataset was created (ISO 8601 format).|string|`'2012-07-29 or 2017-01-17T20:33:40Z'`| 131 | |*updateDateTime**|The time the dataset was updated in (ISO 8601 format).|string|`'2012-07-19 or 2017-01-17T20:33:40Z'`| 132 | |description|Description of the dataset.|string|-| 133 | |version|Version of the dataset.|string|-| 134 | |variantCount|Total number of variants in the dataset.|integer|`230453`| 135 | |callCount|Total number of calls in the dataset.|integer|`213454`| 136 | |sampleCount|Total number of samples in the dataset.|integer|`13`| 137 | |externalUrl|URL to an external system providing more dataset information (RFC 3986 format).|string|-| 138 | |info|Additional structured metadata, key-value pairs.|array|-| 139 | |dataUseConditions|The conditions for the use of the dataset|object|Data Use Conditions object (see below)| 140 | 141 | **Data Use Conditions object** 142 | 143 | 144 | |Properties (* mandatory, ~ one of these is mandatory)|Description|Type|Example| 145 | |---|---|:---:|---| 146 | |*consentCodeDataUse**|The consent code for the use of data.|object|See [GA4GH-CC](https://raw.githubusercontent.com/ga4gh/ga4gh-consent-policy/806ea53cffacb2055c3639f0fc9783f0dcd8cb02/consent_code.yaml#/components/schemas/ConsentCodeDataUse)| 147 | |*adamDataUse**|The Automatable Discovery and Access Matrix (ADA-M) provides a standardized way to unambiguously represent the conditions related to data discovery and access. |object|Adam Data Use Object (see below)| 148 | 149 | **Adam Data Use object** 150 | 151 | |Properties (* mandatory, ~ one of these is mandatory)|Description|Type|Example| 152 | |---|---|:---:|---| 153 | |**header***|General description of what the data is.|object|See [ADA-M](https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Header)| 154 | |**profile***|Profile of the data.|object|See [ADA-M](https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Profile)| 155 | |**terms***|Terms related to the use of the data.|object|See [ADA-M](https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Terms)| 156 | |**metaConditions***|Special conditions.|object|See [ADA-M](https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/MetaConditions)| 157 | 158 | 159 | 160 | 161 | ### Examples 162 | An example `GET` request and response to the info endpoint: 163 | 164 | > GET / HTTP/1.1 165 | > Host: localhost:5000 166 | > User-Agent: curl/7.54.0 167 | > Accept: */* 168 | > 169 | * HTTP 1.0, assume close after body 170 | < HTTP/1.0 200 OK 171 | < Content-Type: application/json 172 | < Content-Length: 2391 173 | < Server: Werkzeug/0.14.1 Python/3.6.5 174 | < Date: Fri, 08 Jun 2018 12:07:36 GMT 175 | < 176 | { 177 | "alternativeUrl": "https://ega-archive.org/beacon_web/", 178 | "apiVersion": "0.4", 179 | "createDateTime": "2015-06-15T00:00.000Z", 180 | "dataset": [ 181 | { 182 | "assemblyId": "grch37", 183 | "callCount": 74, 184 | "description": "This sample set comprises cases of schizophrenia with additional cognitive measurements, collected in Aberdeen, Scotland.", 185 | "id": "EGAD00000000028", 186 | "info": {}, 187 | "sampleCount": 1, 188 | "variantCount": 74, 189 | } 190 | ], 191 | "description": "This Beacon is based on the GA4GH Beacon API 0.4", 192 | "id": "ega-beacon", 193 | "info": { 194 | "size": "60270153" 195 | }, 196 | "name": "EGA Beacon", 197 | "organization": { 198 | "address": "", 199 | "contactUrl": "mailto:beacon.ega@crg.eu", 200 | "description": "The European Genome-phenome Archive (EGA) is a service for permanent archiving and sharing of all types of personally identifiable genetic and phenotypic data resulting from biomedical research projects.", 201 | "id": "EGA", 202 | "logoUrl": "https://ega-archive.org/images/logo.png", 203 | "name": "European Genome-Phenome Archive (EGA)", 204 | "welcomeUrl": "https://ega-archive.org/" 205 | }, 206 | "sampleAlleleRequests": [ 207 | { 208 | "alternateBases": "A", 209 | "assemblyId": "GRCh37", 210 | "includeDatasetResponses": false, 211 | "referenceBases": "C", 212 | "referenceName": "17", 213 | "start": 6689 214 | }, 215 | { 216 | "alternateBases": "G", 217 | "assemblyId": "GRCh37", 218 | "datasetIds": [ 219 | "EGAD00000000028" 220 | ], 221 | "includeDatasetResponses": "ALL", 222 | "referenceBases": "A", 223 | "referenceName": "1", 224 | "start": 14929 225 | }, 226 | { 227 | "alternateBases": "CCCCT", 228 | "assemblyId": "GRCh37", 229 | "datasetIds": [ 230 | "EGAD00001000740", 231 | "EGAD00001000741" 232 | ], 233 | "includeDatasetResponses": "HIT", 234 | "referenceBases": "C", 235 | "referenceName": "1", 236 | "start": 866510 237 | } 238 | ], 239 | "version": "v04", 240 | "welcomeUrl": "https://ega-archive.org/beacon_web/" 241 | } 242 | * Closing connection 0 243 | 244 | ## Query endpoint 245 | 246 | 247 | ### Request 248 | ##### - URL: `/query` 249 | ##### - HTTP method: `GET`, `POST` 250 | ##### - Content-Type: `application/x-www-form-urlencoded`(POST) 251 | ##### - Parameters: `BeaconAlleleRequest` 252 | 253 | **BeaconAlleleRequest object** 254 | 255 | |Parameter (* mandatory, ~ one of these is mandatory)|Description|Type|Example| 256 | |---|---|:---:|---| 257 | |*referenceName**|Reference name (chromosome). Accepting values 1-22, X, Y so follows Ensembl chromosome naming convention.|string|`'1'`| 258 | |*referenceBases**|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 `variantType` as well as `startMin` & `endMin` ... parameters), the use of a single "N" value is required.
See the REF field in [VCF 4.2 specification](https://samtools.github.io/hts-specs/VCFv4.2.pdf).|string|`'G'`| 259 | |*assemblyId* *|Assembly identifier|string|`'GRCh38'`| 260 | |start~|Precise start coordinate position, allele locus (0-based, inclusive).

* `start` only:
- for single positions, e.g. the start of a specified sequence alteration where the size is given through the specified `alternateBases`
- typical use are queries for SNV and small InDels
- the use of `start` without an `end` parameter requires the use of `referenceBases`
* `start` and `end`:
- special use case for exactly determined structural changes |integer|`345233`| 261 | |startMin~|Minimum start coordinate
* `startMin` + `startMax` + `endMin` + `endMax`:
- for querying imprecise positions (e.g. identifying all structural variants starting anywhere between `startMin` <-> `startMax`, and ending anywhere between `endMin` <-> `endMax`
- single or double sided precise matches can be achieved by setting `startMin` = `startMax` OR `endMin` = `endMax`

For more information on range querys, see: [Beacon-Querys](https://github.com/ga4gh-beacon/specification/wiki/Beacon-Queries#range-queries-and-structural-variants)|integer|`23433`| 262 | |startMax|Maximum start coordinate. See `startMin`.|integer|`23450`| 263 | |end|Precise end coordinate (0-based, exclusive). See `start`.|integer|`455635`| 264 | |endMin|Minimum end coordinate. See `startMin`.|integer|`23500`| 265 | |endMax|Maximum end coordinate. See `startMin`.|integer|`23520`| 266 | |alternateBases~|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`.

See the ALT field in [VCF 4.2 specification](https://samtools.github.io/hts-specs/VCFv4.2.pdf)

*Either `alternateBases` OR `variantType` is REQUIRED*|string|`'A'`, `'AGATAC'`| 267 | |variantType~|The `variantType` is used to denote e.g. structural variants.

*Either `alternateBases` OR `variantType` is REQUIRED*|string|`'INS'`, `'DUP'`, `'DEL'`, `'INV'`| 268 | |datasetIds|Identifiers of datasets, as defined in `BeaconDataset`. In case `assemblyId` doesn't match requested dataset(s) error will be raised (`400 Bad request`). If this field is not specified, all datasets should be queried.|array|`['dataset1', 'dataset2']`| 269 | |includeDatasetResponses|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.

Accepted values : ['ALL', 'HIT', 'MISS', 'NONE']|string|`'ALL'`| 270 | 271 | 272 | ### Response 273 | ##### Content-type:`application/json` 274 | ##### Payload: `Beacon Allele Response object` 275 | 276 | **Beacon Allele Response object** 277 | 278 | |Properties (* mandatory, ~ one of these is mandatory)|Description|Type|Example| 279 | |---|---|:---:|---| 280 | |*beaconId**|Identifier of the beacon, as defined in `Beacon`.|string|-| 281 | |apiVersion|Version of the API. If specified, the value must match `apiVersion` in Beacon|string|-| 282 | |exists|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.|boolean|`TRUE`| 283 | |alleleRequest|The request that is sent to the Beacon.|object|BeaconAlleleRequest Object (see above _Query endpoint request_)| 284 | |datasetAlleleResponses|The response that the user receives from the Beacon|object|BeaconDatasetAlleleResponse Object (see below)| 285 | |error|The error message and the appropriate HTTP status code|object|See section _Errors_ | 286 | 287 | **Beacon Dataset Allele Response object** 288 | 289 | |Properties (* mandatory, ~ one of these is mandatory)|Description|Type|Example| 290 | |---|---|:---:|---| 291 | |**datasetId***|Unique identifier of the dataset.|string|-| 292 | |exists|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.|boolean|`TRUE`| 293 | |error|The error message and the appropriate HTTP status code|object|See section _Errors_| 294 | |frequency|Frequency of this allele in the dataset. Between 0 and 1, inclusive.|float|`0.07`| 295 | |variantCount|Number of variants matching the allele request in the dataset.|integer|`2`| 296 | |callCount|Number of calls matching the allele request in the dataset.|integer|`3`| 297 | |sampleCount|Number of samples matching the allele request in the dataset|integer|`1`| 298 | |note|Additional note or description of the response.|string|-| 299 | |externalUrl|URL to an external system, such as a secured beacon or a system providing more information about a given allele (RFC 3986 format).|string|-| 300 | |info|Additional structured metadata, key-value pairs.|array|-| 301 | 302 | 303 | #### Examples 304 | 305 | Example of how to use the GET method in the `/query` endpoint: 306 | 307 | curl -v 'https://localhost:5000/query?referenceName=1&start=0&end=0&startMin=28000000&startMax=29000000&endMin=28000000&endMax=29000000&referenceBases=A&alternateBases=T&assemblyId=GRCh37&datasetIds=EGAD00000000028&includeDatasetResponses=ALL' 308 | ###### 309 | 310 | > GET /query?referenceName=1&start=0&end=0&startMin=28000000&startMax=29000000&endMin=28000000&endMax=29000000&referenceBases=A&alternateBases=T&assemblyId=GRCh37&datasetIds=EGAD00000000028&includeDatasetResponses=ALL HTTP/1.1 311 | > Host: localhost:5000 312 | > User-Agent: curl/7.54.0 313 | > Accept: */* 314 | > 315 | * HTTP 1.0, assume close after body 316 | < HTTP/1.0 200 OK 317 | < Content-Type: application/json 318 | < Content-Length: 1078 319 | < Server: Werkzeug/0.14.1 Python/3.6.5 320 | < Date: Mon, 11 Jun 2018 07:29:26 GMT 321 | < 322 | { 323 | "beaconId": "ega-beacon", 324 | "apiVersion": "0.4", 325 | "exists": true, 326 | "error": null, 327 | "alleleRequest": { 328 | "referenceName": "1", 329 | "start": 0, 330 | "startMin": 28000000, 331 | "startMax": 29000000, 332 | "end": 0, 333 | "endMin": 28000000, 334 | "endMax": 29000000, 335 | "referenceBases": "A", 336 | "alternateBases": "T", 337 | "assemblyId": "GRCh37", 338 | "datasetIds": [ 339 | "EGAD00000000028" 340 | ], 341 | "includeDatasetResponses": "ALL" 342 | }, 343 | "datasetAlleleResponses": [ 344 | { 345 | "datasetId": "EGAD00000000028", 346 | "exists": true, 347 | "frequency": 0.5, 348 | "variantCount": 1, 349 | "callCount": 1, 350 | "sampleCount": 1, 351 | "note": "This sample set comprises cases of schizophrenia with additional cognitive measurements, collected in Aberdeen, Scotland.", 352 | "externalUrl": null, 353 | "info": {}, 354 | "error": null 355 | } 356 | ] 357 | } 358 | * Closing connection 0 359 | 360 | ###### 361 | Example of how to use the POST method in the "/query" path: 362 | 363 | curl -v -d "referenceName=1&start=14929&referenceBases=A&alternateBases=G&assemblyId=GRCh37&datasetIds=EGAD00000000028&includeDatsetResponses=ALL" https://localhost:5000/query 364 | ###### 365 | 366 | > POST /query HTTP/1.1 367 | > Host: localhost:5000 368 | > User-Agent: curl/7.54.0 369 | > Accept: */* 370 | > Content-Length: 133 371 | > Content-Type: application/x-www-form-urlencoded 372 | > 373 | * upload completely sent off: 133 out of 133 bytes 374 | * HTTP 1.0, assume close after body 375 | < HTTP/1.0 200 OK 376 | < Content-Type: application/json 377 | < Content-Length: 1056 378 | < Server: Werkzeug/0.14.1 Python/3.6.5 379 | < Date: Mon, 11 Jun 2018 07:15:48 GMT 380 | < 381 | { 382 | "beaconId": "ega-beacon", 383 | "apiVersion": "0.4", 384 | "exists": true, 385 | "error": null, 386 | "alleleRequest": { 387 | "referenceName": "1", 388 | "start": 14929, 389 | "startMin": 0, 390 | "startMax": 0, 391 | "end": 0, 392 | "endMin": 0, 393 | "endMax": 0, 394 | "referenceBases": "A", 395 | "alternateBases": "G", 396 | "assemblyId": "GRCh37", 397 | "datasetIds": [ 398 | "EGAD00000000028" 399 | ], 400 | "includeDatasetResponses": "ALL" 401 | }, 402 | "datasetAlleleResponses": [ 403 | { 404 | "datasetId": "EGAD00000000028", 405 | "exists": true, 406 | "frequency": 0.5, 407 | "variantCount": 1, 408 | "callCount": 1, 409 | "sampleCount": 1, 410 | "note": "This sample set comprises cases of schizophrenia with additional cognitive measurements, collected in Aberdeen, Scotland.", 411 | "externalUrl": null, 412 | "info": {}, 413 | "error": null 414 | } 415 | ] 416 | } 417 | * Closing connection 0 418 | 419 | `curl -v 'https://localhost:5000/query?&start=0&end=0&startMin=28000000&startMax=29000000&endMin=28000000&endMax=29000000&referenceBases=A&alternateBases=T&assemblyId=GRCh37&datasetIds=EGAD00000000028&includeDatasetResponses=ALL'` 420 | 421 | 422 | ``` 423 | * Trying 127.0.0.1... 424 | * TCP_NODELAY set 425 | * Connected to localhost (127.0.0.1) port 5000 (#0) 426 | > GET /query?&start=0&end=0&startMin=28000000&startMax=29000000&endMin=28000000&endMax=29000000&referenceBases=A&alternateBases=T&assemblyId=GRCh37&datasetIds=EGAD00000000028&includeDatasetResponses=ALL HTTP/1.1 427 | > Host: localhost:5000 428 | > User-Agent: curl/7.54.0 429 | > Accept: */* 430 | > 431 | * HTTP 1.0, assume close after body 432 | < HTTP/1.0 400 BAD REQUEST 433 | < Content-Type: application/json 434 | < Content-Length: 791 435 | < Server: Werkzeug/0.14.1 Python/3.6.5 436 | < Date: Fri, 06 Jul 2018 09:15:39 GMT 437 | < 438 | { 439 | "message": { 440 | "beaconId": "ega-beacon", 441 | "apiVersion": "0.4", 442 | "exists": null, 443 | "error": { 444 | "errorCode": 400, 445 | "errorMessage": "Missing mandatory parameter referenceName" 446 | }, 447 | "allelRequest": { 448 | "referenceName": "0", 449 | "start": 0, 450 | "startMin": 28000000, 451 | "startMax": 29000000, 452 | "end": 0, 453 | "endMin": 28000000, 454 | "endMax": 29000000, 455 | "referenceBases": "A", 456 | "alternateBases": "T", 457 | "variantType": "0", 458 | "assemblyId": "GRCh37", 459 | "datasetIds": [ 460 | "EGAD00000000028" 461 | ], 462 | "includeDatasetResponses": "ALL" 463 | }, 464 | "datasetAlleleResponses": [] 465 | } 466 | } 467 | * Closing connection 0 468 | 469 | ``` 470 | -------------------------------------------------------------------------------- /beacon.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | servers: [] 3 | info: 4 | version: "1.0.1" 5 | title: GA4GH Beacon API Specification 6 | description: >- 7 | A Beacon is a web service for genetic data sharing that can be queried for information about specific alleles. 8 | contact: 9 | email: beacon@ga4gh.org 10 | license: 11 | name: Apache 2.0 12 | url: 'http://www.apache.org/licenses/LICENSE-2.0.html' 13 | externalDocs: 14 | description: 'Beacon Project' 15 | url: 'http://beacon-project.io/' 16 | paths: 17 | /: 18 | get: 19 | description: Get information about the beacon 20 | operationId: getBeacon 21 | responses: 22 | '200': 23 | description: successful operation 24 | content: 25 | application/json: 26 | schema: 27 | $ref: '#/components/schemas/Beacon' 28 | /query: 29 | get: 30 | description: Get response to a beacon query for allele information. 31 | operationId: getBeaconAlleleResponse 32 | parameters: 33 | - name: referenceName 34 | description: 'Reference name (chromosome). Accepting values 1-22, X, Y, MT.' 35 | in: query 36 | required: true 37 | schema: 38 | $ref: '#/components/schemas/Chromosome' 39 | - name: start 40 | description: | 41 | Precise start coordinate position, allele locus (0-based, inclusive). 42 | * start only: 43 | - for single positions, e.g. the start of a specified sequence alteration where the size is given through the specified alternateBases 44 | - typical use are queries for SNV and small InDels 45 | - the use of "start" without an "end" parameter requires the use of "referenceBases" 46 | * start and end: 47 | - special use case for exactly determined structural changes 48 | in: query 49 | required: false 50 | schema: 51 | type: integer 52 | format: int64 53 | minimum: 0 54 | - name: startMin 55 | description: | 56 | Minimum start coordinate 57 | * startMin + startMax + endMin + endMax 58 | - for querying imprecise positions (e.g. identifying all structural variants starting anywhere between startMin <-> startMax, and ending anywhere between endMin <-> endMax) 59 | - single or double sided precise matches can be achieved by setting startMin = startMax XOR endMin = endMax 60 | in: query 61 | schema: 62 | type: integer 63 | format: int64 64 | minimum: 0 65 | - name: startMax 66 | description: | 67 | Maximum start coordinate. See startMin. 68 | in: query 69 | schema: 70 | type: integer 71 | format: int64 72 | minimum: 0 73 | - name: end 74 | description: | 75 | Precise end coordinate (0-based, exclusive). See start. 76 | in: query 77 | schema: 78 | type: integer 79 | format: int64 80 | minimum: 0 81 | - name: endMin 82 | description: | 83 | Minimum end coordinate. See startMin. 84 | in: query 85 | schema: 86 | type: integer 87 | format: int64 88 | minimum: 0 89 | - name: endMax 90 | description: | 91 | Maximum end coordinate. See startMin. 92 | in: query 93 | schema: 94 | type: integer 95 | format: int64 96 | minimum: 0 97 | - name: referenceBases 98 | description: > 99 | Reference bases for this variant (starting from `start`). Accepted 100 | values: [ACGT]* 101 | 102 | When querying for variants without specific base alterations (e.g. 103 | imprecise structural variants with separate variant_type as well as 104 | start_min & end_min ... parameters), the use of a single "N" value 105 | is required. 106 | in: query 107 | required: true 108 | schema: 109 | type: string 110 | pattern: '^([ACGT]+|N)$' 111 | - name: alternateBases 112 | description: > 113 | The bases that appear instead of the reference bases. Accepted 114 | values: [ACGT]* or N. 115 | 116 | Symbolic ALT alleles (DEL, INS, DUP, INV, CNV, DUP:TANDEM, DEL:ME, 117 | INS:ME) will be represented in `variantType`. 118 | 119 | Optional: either `alternateBases` or `variantType` is required. 120 | in: query 121 | required: false 122 | schema: 123 | type: string 124 | pattern: '^([ACGT]+|N)$' 125 | - name: variantType 126 | description: > 127 | The `variantType` is used to denote e.g. structural variants. 128 | 129 | Examples: 130 | * DUP: duplication of sequence following `start`; not necessarily in 131 | situ 132 | * DEL: deletion of sequence following `start` 133 | 134 | Optional: either `alternateBases` or `variantType` is required. 135 | in: query 136 | required: false 137 | schema: 138 | type: string 139 | examples: 140 | dup: 141 | value: DUP 142 | summary: duplication of sequence following `start`; not necessarily in 143 | del: 144 | value: DEL 145 | summary: deletion of sequence following `start` 146 | - name: assemblyId 147 | description: 'Assembly identifier (GRC notation, e.g. GRCh37).' 148 | in: query 149 | required: true 150 | schema: 151 | type: string 152 | - name: datasetIds 153 | description: >- 154 | Identifiers of datasets, as defined in "BeaconDataset". If this 155 | field is null/not specified, all datasets should be queried. 156 | in: query 157 | required: false 158 | explode: true 159 | schema: 160 | type: array 161 | items: 162 | type: string 163 | - name: includeDatasetResponses 164 | description: > 165 | Indicator of whether responses for individual datasets 166 | (datasetAlleleResponses) should be included in the response 167 | (BeaconAlleleResponse) to this request or not. 168 | 169 | If null (not specified), the default value of NONE is assumed. 170 | in: query 171 | required: false 172 | schema: 173 | type: string 174 | enum: 175 | - ALL 176 | - HIT 177 | - MISS 178 | - NONE 179 | responses: 180 | '200': 181 | description: successful operation 182 | content: 183 | application/json: 184 | schema: 185 | items: 186 | $ref: '#/components/schemas/BeaconAlleleResponse' 187 | '400': 188 | description: Bad request (e.g. missing mandatory parameter) 189 | content: 190 | application/json: 191 | schema: 192 | $ref: '#/components/schemas/BeaconAlleleResponse' 193 | '401': 194 | description: >- 195 | Unauthorised (e.g. when an unauthenticated user tries to access a 196 | protected resource) 197 | content: 198 | application/json: 199 | schema: 200 | $ref: '#/components/schemas/BeaconAlleleResponse' 201 | '403': 202 | description: >- 203 | Forbidden (e.g. the resource is protected for all users or the user 204 | is authenticated but s/he is not granted for this resource) 205 | content: 206 | application/json: 207 | schema: 208 | $ref: '#/components/schemas/BeaconAlleleResponse' 209 | post: 210 | description: Gets response to a beacon query for allele information. 211 | operationId: postBeaconAlleleResponse 212 | responses: 213 | '200': 214 | description: successful operation 215 | content: 216 | application/json: 217 | schema: 218 | items: 219 | $ref: '#/components/schemas/BeaconAlleleResponse' 220 | '400': 221 | description: Bad request (e.g. missing mandatory parameter) 222 | content: 223 | application/json: 224 | schema: 225 | $ref: '#/components/schemas/BeaconAlleleResponse' 226 | '401': 227 | description: >- 228 | Unauthorised (e.g. when an unauthenticated user tries to access a 229 | protected resource) 230 | content: 231 | application/json: 232 | schema: 233 | $ref: '#/components/schemas/BeaconAlleleResponse' 234 | '403': 235 | description: >- 236 | Forbidden (e.g. the resource is protected for all users or the user 237 | is authenticated but s/he is not granted for this resource) 238 | content: 239 | application/json: 240 | schema: 241 | $ref: '#/components/schemas/BeaconAlleleResponse' 242 | requestBody: 243 | content: 244 | application/json: 245 | schema: 246 | $ref: '#/components/schemas/BeaconAlleleRequest' 247 | required: true 248 | components: 249 | schemas: 250 | Chromosome: 251 | description: 'Reference name (chromosome). Accepting values 1-22, X, Y.' 252 | type: string 253 | enum: 254 | - '1' 255 | - '2' 256 | - '3' 257 | - '4' 258 | - '5' 259 | - '6' 260 | - '7' 261 | - '8' 262 | - '9' 263 | - '10' 264 | - '11' 265 | - '12' 266 | - '13' 267 | - '14' 268 | - '15' 269 | - '16' 270 | - '17' 271 | - '18' 272 | - '19' 273 | - '20' 274 | - '21' 275 | - '22' 276 | - 'X' 277 | - 'Y' 278 | - 'MT' 279 | Beacon: 280 | type: object 281 | required: 282 | - id 283 | - name 284 | - apiVersion 285 | - organization 286 | - datasets 287 | properties: 288 | id: 289 | type: string 290 | description: Unique identifier of the beacon. Use reverse domain name notation. 291 | example: org.ga4gh.beacon 292 | name: 293 | type: string 294 | description: Name of the beacon. 295 | apiVersion: 296 | type: string 297 | description: Version of the API provided by the beacon. 298 | example: v0.3 299 | organization: 300 | $ref: '#/components/schemas/BeaconOrganization' 301 | description: 302 | type: string 303 | description: Description of the beacon. 304 | version: 305 | type: string 306 | description: Version of the beacon. 307 | example: v0.1 308 | welcomeUrl: 309 | type: string 310 | description: URL to the welcome page for this beacon (RFC 3986 format). 311 | example: 'http://example.org/wiki/Main_Page' 312 | alternativeUrl: 313 | type: string 314 | description: >- 315 | Alternative URL to the API, e.g. a restricted version of this beacon 316 | (RFC 3986 format). 317 | example: 'http://example.org/wiki/Main_Page' 318 | createDateTime: 319 | type: string 320 | description: The time the beacon was created (ISO 8601 format). 321 | example: '2012-07-19 or 2017-01-17T20:33:40Z' 322 | updateDateTime: 323 | type: string 324 | description: The time the beacon was updated in (ISO 8601 format). 325 | example: '2012-07-19 or 2017-01-17T20:33:40Z' 326 | datasets: 327 | description: >- 328 | Dataset(s) served by the beacon. 329 | minItems: 1 330 | type: array 331 | items: 332 | $ref: '#/components/schemas/BeaconDataset' 333 | sampleAlleleRequests: 334 | description: >- 335 | Examples of interesting queries, e.g. a few queries demonstrating 336 | different responses. 337 | type: array 338 | items: 339 | $ref: '#/components/schemas/BeaconAlleleRequest' 340 | info: 341 | description: 'Additional structured metadata, key-value pairs.' 342 | type: array 343 | items: 344 | $ref: '#/components/schemas/KeyValuePair' 345 | BeaconAlleleRequest: 346 | description: Allele request as interpreted by the beacon. 347 | type: object 348 | required: 349 | - referenceName 350 | - referenceBases 351 | - assemblyId 352 | properties: 353 | referenceName: 354 | $ref: '#/components/schemas/Chromosome' 355 | start: 356 | description: | 357 | Precise start coordinate position, allele locus (0-based, inclusive). 358 | * start only: 359 | - for single positions, e.g. the start of a specified sequence alteration where the size is given through the specified alternateBases 360 | - typical use are queries for SNV and small InDels 361 | - the use of "start" without an "end" parameter requires the use of "referenceBases" 362 | * start and end: 363 | - special use case for exactly determined structural changes 364 | type: integer 365 | format: int64 366 | minimum: 0 367 | end: 368 | description: Precise end coordinate (0-based, exclusive). See start. 369 | type: integer 370 | startMin: 371 | description: | 372 | Minimum start coordinate 373 | * startMin + startMax + endMin + endMax 374 | - for querying imprecise positions (e.g. identifying all structural variants starting anywhere between startMin <-> startMax, and ending anywhere between endMin <-> endMax) 375 | - single or double sided precise matches can be achieved by setting startMin = startMax XOR endMin = endMax 376 | type: integer 377 | startMax: 378 | description: Maximum start coordinate. See startMin. 379 | type: integer 380 | endMin: 381 | description: Minimum end coordinate. See startMin. 382 | type: integer 383 | endMax: 384 | description: Maximum end coordinate. See startMin. 385 | type: integer 386 | referenceBases: 387 | description: > 388 | Reference bases for this variant (starting from `start`). Accepted 389 | values: [ACGT]* 390 | 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. 391 | type: string 392 | pattern: '^([ACGT]+|N)$' 393 | alternateBases: 394 | description: > 395 | The bases that appear instead of the reference bases. Accepted 396 | values: [ACGT]* or N. 397 | 398 | Symbolic ALT alleles (DEL, INS, DUP, INV, CNV, DUP:TANDEM, DEL:ME, 399 | INS:ME) will be represented in `variantType`. 400 | 401 | Optional: either `alternateBases` or `variantType` is required. 402 | type: string 403 | pattern: '^([ACGT]+|N)$' 404 | variantType: 405 | description: > 406 | The `variantType` is used to denote e.g. structural variants. 407 | 408 | Examples: 409 | 410 | * DUP: duplication of sequence following `start`; not necessarily in 411 | situ 412 | 413 | * DEL: deletion of sequence following `start` 414 | 415 | 416 | Optional: either `alternateBases` or `variantType` is required. 417 | type: string 418 | assemblyId: 419 | description: 'Assembly identifier (GRC notation, e.g. `GRCh37`).' 420 | type: string 421 | example: GRCh38 422 | datasetIds: 423 | description: >- 424 | Identifiers of datasets, as defined in `BeaconDataset`. If this 425 | field is null/not specified, all datasets should be queried. 426 | type: array 427 | items: 428 | type: string 429 | includeDatasetResponses: 430 | description: >- 431 | Indicator of whether responses for individual datasets 432 | (datasetAlleleResponses) should be included in the response 433 | (BeaconAlleleResponse) to this request or not. If null (not 434 | specified), the default value of NONE is assumed. 435 | type: string 436 | enum: 437 | - ALL 438 | - HIT 439 | - MISS 440 | - NONE 441 | BeaconAlleleResponse: 442 | type: object 443 | required: 444 | - beaconId 445 | properties: 446 | beaconId: 447 | description: 'Identifier of the beacon, as defined in `Beacon`.' 448 | type: string 449 | apiVersion: 450 | description: >- 451 | Version of the API. If specified, the value must match `apiVersion` 452 | in Beacon 453 | type: string 454 | exists: 455 | description: >- 456 | Indicator of whether the given allele was observed in any of the 457 | datasets queried. This should be non-null, unless there was an 458 | error, in which case `error` has to be non-null. 459 | type: boolean 460 | alleleRequest: 461 | $ref: '#/components/schemas/BeaconAlleleRequest' 462 | datasetAlleleResponses: 463 | description: >- 464 | Indicator of whether the given allele was observed in individual 465 | datasets. This should be non-null if `includeDatasetResponses` in 466 | the corresponding `BeaconAlleleRequest` is true, and null otherwise. 467 | type: array 468 | items: 469 | $ref: '#/components/schemas/BeaconDatasetAlleleResponse' 470 | error: 471 | $ref: '#/components/schemas/BeaconError' 472 | BeaconOrganization: 473 | description: Organization owning the beacon. 474 | type: object 475 | required: 476 | - id 477 | - name 478 | properties: 479 | id: 480 | type: string 481 | description: Unique identifier of the organization. 482 | name: 483 | type: string 484 | description: Name of the organization. 485 | description: 486 | type: string 487 | description: Description of the organization. 488 | address: 489 | type: string 490 | description: Address of the organization. 491 | welcomeUrl: 492 | type: string 493 | description: URL of the website of the organization (RFC 3986 format). 494 | contactUrl: 495 | type: string 496 | description: >- 497 | URL with the contact for the beacon operator/maintainer, e.g. link 498 | to a contact form (RFC 3986 format) or an email (RFC 2368 format). 499 | logoUrl: 500 | type: string 501 | description: >- 502 | URL to the logo (PNG/JPG format) of the organization (RFC 3986 503 | format). 504 | info: 505 | description: 'Additional structured metadata, key-value pairs.' 506 | type: array 507 | items: 508 | $ref: '#/components/schemas/KeyValuePair' 509 | BeaconDataset: 510 | type: object 511 | required: 512 | - id 513 | - name 514 | - assemblyId 515 | - createDateTime 516 | - updateDateTime 517 | properties: 518 | id: 519 | type: string 520 | description: Unique identifier of the dataset. 521 | name: 522 | type: string 523 | description: Name of the dataset. 524 | description: 525 | type: string 526 | description: Description of the dataset. 527 | assemblyId: 528 | description: 'Assembly identifier (GRC notation, e.g. `GRCh37`).' 529 | type: string 530 | example: GRCh38 531 | createDateTime: 532 | type: string 533 | description: The time the dataset was created (ISO 8601 format). 534 | example: '2012-07-29 or 2017-01-17T20:33:40Z' 535 | updateDateTime: 536 | type: string 537 | description: The time the dataset was updated in (ISO 8601 format). 538 | example: '2012-07-19 or 2017-01-17T20:33:40Z' 539 | version: 540 | type: string 541 | description: Version of the dataset. 542 | variantCount: 543 | type: integer 544 | format: int64 545 | description: Total number of variants in the dataset. 546 | minimum: 0 547 | callCount: 548 | type: integer 549 | format: int64 550 | description: Total number of calls in the dataset. 551 | minimum: 0 552 | sampleCount: 553 | type: integer 554 | format: int64 555 | description: Total number of samples in the dataset. 556 | minimum: 0 557 | externalUrl: 558 | type: string 559 | description: >- 560 | URL to an external system providing more dataset information (RFC 561 | 3986 format). 562 | example: 'http://example.org/wiki/Main_Page' 563 | info: 564 | description: 'Additional structured metadata, key-value pairs.' 565 | type: array 566 | items: 567 | $ref: '#/components/schemas/KeyValuePair' 568 | dataUseConditions: 569 | $ref: '#/components/schemas/DataUseConditions' 570 | BeaconDatasetAlleleResponse: 571 | type: object 572 | required: 573 | - datasetId 574 | properties: 575 | datasetId: 576 | type: string 577 | description: not provided 578 | exists: 579 | description: >- 580 | Indicator of whether the given allele was observed in the dataset. 581 | This should be non-null, unless there was an error, in which case 582 | `error` has to be non-null. 583 | type: boolean 584 | error: 585 | $ref: '#/components/schemas/BeaconError' 586 | frequency: 587 | type: number 588 | description: 'Frequency of this allele in the dataset. Between 0 and 1, inclusive.' 589 | minimum: 0 590 | maximum: 1 591 | variantCount: 592 | type: integer 593 | format: int64 594 | description: Number of variants matching the allele request in the dataset. 595 | minimum: 0 596 | callCount: 597 | type: integer 598 | format: int64 599 | description: Number of calls matching the allele request in the dataset. 600 | minimum: 0 601 | sampleCount: 602 | type: integer 603 | format: int64 604 | description: Number of samples matching the allele request in the dataset 605 | minimum: 0 606 | note: 607 | type: string 608 | description: Additional note or description of the response. 609 | externalUrl: 610 | type: string 611 | description: >- 612 | URL to an external system, such as a secured beacon or a system 613 | providing more information about a given allele (RFC 3986 format). 614 | info: 615 | description: 'Additional structured metadata, key-value pairs.' 616 | type: array 617 | items: 618 | $ref: '#/components/schemas/KeyValuePair' 619 | BeaconError: 620 | description: >- 621 | Beacon-specific error. This should be non-null in exceptional situations 622 | only, in which case `exists` has to be null. 623 | type: object 624 | required: 625 | - errorCode 626 | properties: 627 | errorCode: 628 | type: integer 629 | format: int32 630 | example: 'same as HTTP status code' 631 | errorMessage: 632 | type: string 633 | KeyValuePair: 634 | type: object 635 | required: 636 | - key 637 | - value 638 | properties: 639 | key: 640 | type: string 641 | value: 642 | type: string 643 | DataUseConditions: 644 | type: object 645 | required: 646 | - consentCodeDataUse 647 | - adamDataUse 648 | description: Data use conditions ruling this dataset. 649 | properties: 650 | consentCodeDataUse: 651 | $ref: >- 652 | https://raw.githubusercontent.com/ga4gh/ga4gh-consent-policy/806ea53cffacb2055c3639f0fc9783f0dcd8cb02/consent_code.yaml#/components/schemas/ConsentCodeDataUse 653 | adamDataUse: 654 | $ref: '#/components/schemas/AdamDataUse' 655 | AdamDataUse: 656 | type: object 657 | required: 658 | - header 659 | - profile 660 | - terms 661 | - metaConditions 662 | properties: 663 | header: 664 | $ref: >- 665 | https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Header 666 | profile: 667 | $ref: >- 668 | https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Profile 669 | terms: 670 | $ref: >- 671 | https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/Terms 672 | metaConditions: 673 | $ref: >- 674 | https://raw.githubusercontent.com/ga4gh/ADA-M/b16a72f9987ae20f433e97d6a3247ecddd8dde23/adam.yaml#/components/schemas/MetaConditions 675 | --------------------------------------------------------------------------------