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 - URL change, new options

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

and

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

becomes

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

We also allow a limited list of VEP arguments to be appended to the URL instead of using a set of universal options. 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.

Archive format acquires POST support

In the event of using the archive endpoint heavily, consider switching to POST messages containing batches of IDs.

  • Set your accepts header to application/json
  • Set your content-type to application/json
  • The message body consists of the key "id" followed by a list of IDs.
  • Archive lookups are not as fast as the VEP, please limit your requests to 400 IDs per batch for decent performance and respectful usage.

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 acquire new masking option

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 URL change

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

Feature endpoint URL changed to overlap

The function of [/feature/*] endpoints was 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.

Assembly endpoint URL changed

[/assembly/info] has been renamed to [/info/assembly] in order to fit with other info endpoints.

Rate limiter increased

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