-
Notifications
You must be signed in to change notification settings - Fork 63
Output formats
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
-
Content-type
HTTP header -
content-type
HTTP parameter -
Accept
HTTP in header - File extension
-
- POST
-
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
.
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.
In this example we will specify the JSON output format in the four supported ways using the ping endpoint:
curl -H "Content-Type: application/json" http://rest.ensembl.org/info/ping
curl http://rest.ensembl.org/info/ping?content-type=application/json
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
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
curl -H 'Accept:' URL
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 /feature endpoint. |
BED | text/x-bed |
.bed |
Browser Extensible Data format as defined by UCSC. Only supported on the /feature 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 end points |
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 end points |
XML | text/xml |
.xml |
- |
YAML | text/x-yaml |
.yaml |
- |