Output formats - Ensembl/ensembl-rest GitHub Wiki

Types

Ensembl REST supports a number of standard language formats such as JSON but also a number of bioinformatical formats e.g. FASTA. Specifying the value depends heavily on your client and the type of operation you are executing. GET requests support 4 ways of specifying the format. POST only supports one.

GET
1. Content-type HTTP header
2. content-type HTTP parameter
3. Accept HTTP in header
4. File extension
POST
1. Accept HTTP header

Be aware that some characters such as + can be interpreted incorrectly when given as a parameter rather than a header; instead use the URL encoded version of the character e.g. instead of + use %2B. In addition, the header and paramter keywords are case senstive, please note the different cases for Content-type and content-type.

Structure of a MIME Type

Mime types are constructed of 2 portions separated by a /. The first describes the media type and the second part gives the name of said media with an optional suffix. text indicates the content is human readable. application indicates a multipurpose file but most likely not for direct human consumption. Names of media can be prefixed with a x- stating that the MIME type is not part of the official IANA list of MIME types. Finally the name can have a suffix when a MIME type is actually another format.

For example PhyloXML's type is text/x-phyloxml+xml. This indicates that the content could be suitable for human reading, it is a non-standard MIME type and is actually XML and should be handled as such. More advanced clients can look at these values and pass back appropriate data structures depending on the value. Both browsers and libraries like jQuery do this.

GET

In this example we will specify the JSON output format in the four supported ways using the ping endpoint:

Content-Type Header

curl -H "Content-Type: application/json" \
http://rest.ensembl.org/info/ping

Content-Type Parameter

curl http://rest.ensembl.org/info/ping?content-type=application/json

Accept Header

Whilst Accept is the generally regarded correct way to specify content encoding it is not the default in Ensembl's REST API for GET requests only. Web browsers such as Chrome send an Accept header along with each request by default which if we always looked at would mean you could not get a different output from the service when querying from within your web browser. A typical web browser Accept header looks like Accept:text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8. This means we would attempt to serve HTML first, then XHTML, XML and images. Finally */* is the browser telling REST to serve something it believes is appropriate.

curl -H "Accept: application/json" \
http://rest.ensembl.org/info/ping

File extension

GETs allow you to use common file extensions to indicate the required output format. See later for more information on the types of file extensions we support.

curl http://rest.ensembl.org/info/ping.json

POST

POST requests can respond to the Accept and Content-type header however Accept is the correct way to do this. Content-type should be used to refer to the encoding of your request body e.g. application/json or application/x-www-form-urlencoded. Here we request JSON as our input (using Content-Type) and our output (using Accept).

curl -H 'Accept: application/json' \
-H 'Content-type: application/json' -X POST \
-d '{ "ids" : ["rs116035550", "COSM476" ] }' \
http://rest.ensembl.org/vep/human/id/

Supported MIME Types

Format	Content-type	Extension	Notes
FASTA	`text/x-fasta`	`.fasta`	Sequence serialisation format. Only supported on the /sequence endpoint.
GFF3	`text/x-gff3`	`.gff3`	Genomic feature serialisation format. Only supported on the /overlap endpoint.
BED	`text/x-bed`	`.bed`	Browser Extensible Data format as defined by UCSC. Only supported on the /overlap endpoint.
JSON	`application/json`	`.json`	JavaScript compatible generic text based serialisation format. Supported by most programming languages and the recommended consumption format
JSONP	`text/javascript`	`.jsonp`	Extension of JSON to avoid issues of web browser same origin policy. Commonly used by JavaScript plugins like jQuery.
Newick (New Hampshire) format	`text/x-nh`	`.nh`	Phylogenetic serialisation format. Used in /genetree endpoints
SeqXML	`text/x-seqxml+xml`	`.seqxml`	XML schema used to hold sequence information
PhyloXML	`text/x-phyloxml+xml`	`.phyloxml`	XML phylogenetic serialisation format. Used in /genetree endpoints
XML	`text/xml`	`.xml`	-
YAML	`text/x-yaml`	`.yaml`	-