Versions & Release Schedule
Introduction
VarSome API is a programmatic way of accessing VarSome.com knowledge base, which allows you to pull down:
- All resources from the public domain
- Additional resources available under VarSome Premium
- All contributions from the global VarSome's community
- Germline classification, with full explanations
We offer 3 API environments, with different levels of stability both for annotation data sets as well as for data models and schemes. Understanding the differences and using the right environment is crucial to avoid unexpected functionality disruption of your application.
Understanding the differences
The following table details the characteristics of these environments and their intended use:
|
Stable |
Live |
Staging |
|
|
URL |
stable-api.varsome.com |
api.varsome.com |
staging-api.varsome.com |
|
Purpose |
A frozen stable version suitable for production use. |
Suitable for experimental use. |
A test environment reflecting the next Stable release of the API. |
|
Release Schedule |
Quarterly. Second Friday of March, June, September, December, at approx noon UTC. |
At our discretion. Monthly data updates. |
Will be frozen for a period of at least 4 weeks prior to a release to the Stable environment. At other times, it will be updated at our discretion, either together with Live or possibly ahead to test new features. |
|
Data Quality |
High, but only updated quarterly, may lag by up to 6 months. |
High, with the most up-to-date data available including the latest user community contributions. |
A substantial but partial data-set (TBD). The actual data may be ahead of the Live environment. |
|
Usage |
Unthrottled. Covered by current API fee for Subscribers. |
Unthrottled. Covered by current API fee for Subscribers. |
Throttled. Free usage, however only for Subscribers |
|
Availability |
Very High. |
Very High. |
Best effort, and good availability prior to release. |
|
Communication |
Subscribers will be warned at least 4 weeks in advance of any change and will be provided with a list of the expected differences. |
API release notes, typically issued on the day of the release. |
Ad-hoc for unscheduled maintenance and updates. Clear notification 4 weeks before a Stable release that the new API schemes & data are available for testing. |
Release Process
- At least 4 weeks prior to an update to the Stable version, we will deploy the updated release package and most up-to-date data set to the Staging environment, and distribute a set of change notices detailing how the API, classifications, or data have changed since the prior release.
- Subscribers using the Stable environment will then have 4 weeks in order to update & test their software. They must notify us at the earliest possible time of any issues they find or if they will not be ready in time.
- The Staging environment may still be updated during the testing period should any major bug or issue be reported.
- Based on the feedback, state of readiness, and at our discretion, API schemes & data versions deployed on the Staging server will be migrated to the Stable server and it will be restarted.
- The Staging server will remain frozen for a further week and will be subsequently updated to reflect the Live or internal development versions of the software & data.