Skip to content
Snippets Groups Projects

1.0 To 2.0 Migration

Last edited by Kieron Taylor

Migrating your beta REST service client to work with release 2.0.0

The majority of functionality remains the same, but a few key changes have taken place to specific endpoints and general operation. Chiefly, our URL changes from beta.rest.ensembl.org to rest.ensembl.org. Read on:

The VEP

The popularity of the VEP has driven us to add POST support to improve turnaround time for bulk requests. The URL has been simplified as well.

/vep/human/9:22125503-22125502:1/C/consequences?content-type=application/json becomes /vep/human/region/9:22125503-22125502:1/C?content-type=application/json

/vep/human/id/COSM476/consequences?content-type=application/json becomes /vep/human/id/COSM476?content-type=application/json

Instead of forcing a set of default options, we also allow a limited list of VEP arguments to be appended to the URL. For example, to turn on 1000 Genomes MAF annotation and include HGVS nomenclature:

/vep/human/id/rs116035550?content-type=application/json;hgvs=1;maf_1kg=1

See the REST endpoint documentation for specifics.

In the event of processing larger numbers of variants, please switch to using the POST message type encoded in JSON format.

  • Set your accepts header to application/json
  • Set your content-type to one of those available
  • The message body consists of a key (ids or variants) depending on the endpoint followed by a list of values.
  • [/vep/:species/region] accepts variants in all the VEP-supported formats, with one line of the original file comprising one element of the list. Examples of these formats can be found in the Ensembl VEP help page
  • VEP options (hgvs, maf_1kg etc.) can be specified as additional keys in the message body as well as URL parameters.
  • batch your requests by up to one thousand per POST and wait patiently. This is a shared resource, and excessive requests will not increase performance but will impact other users.

Retirement of underused formats messagepack and sereal

In the unlikely event that you chose to use messagepack or sereal for your output format, please switch to using JSON. JSON will be the primary supported input and output format for Ensembl REST, and there are good libraries in all common languages to transparently handle this data format.

Sequence endpoints

The URL remains the same, but a new masking option mask_feature has been introduced in response to the need for visible intron and CDS boundaries.

Ontology endpoints

Following a surge of pedantry, [/ontology/descendents] is now renamed [/ontology/descendants]. The function remains the same.

Feature endpoint changed to overlap

The function of [/feature/] endpoints were being misconstrued. As a result they have been renamed to [/overlap/], to indicate that they find features that share the location with the feature used as input data.

Rate limiter

The basic rate limit has been increased to 15 requests per second. You can increase the client rate to match.