HTTP Headers - Ensembl/ensembl-rest GitHub Wiki

Introduction

Ensembl REST uses a number of HTTP headers in REST to flag various parts of metadata to the user or to allow the user to influence what the REST API does. Understanding these headers is vital to proper usage of the REST API.

Any header starting with a X- is a non-standard header and is used by the REST API to communicate something specific about the service.

Request Headers

Header	Type	Description	Example
Accept	MIME Type	The required encoding of the response body. Supported in both GET and POST	text/x-fasta
Accept-Encoding	String	Flag that you can handle a compressed response body (gzip or deflate) and will decompress it before using it. Very useful to speed up your transfers	gzip, gzip,deflate
Content-Type	MIME Type	When used in a POST it flags the encoding of the request body only. In GET it flags the required encoding of the response.	application/json
Origin	URL	Specifies an origin domain from which a request is being made. Used with CORS	Origin: http://www.example.com

Response Headers

Header	Type	Description	Example
Access-Control-Allow-Origin	URL	Responds with the domains allowed to interact with REST without violating same origin policy. Used with CORS. This defaults to * (we allow any website to script against us).	Access-Control-Allow-Origin: *
Content-Length	Integer	Show how long the content is in bytes	14
Content-Type	MIME Type	The encoding of the response body	text/x-fasta
Retry-After	Float	Sent back when we hit a 429 error and exceed the rate limit. Client should wait for this period before sending another request	1.0232
X-Runtime	Float	How long the request took to execute on our server	0.0032
X-RateLimit-Limit	Integer	How many requests you are allowed to execute within a rate limited time period	55000
X-RateLimit-Reset	Seconds	How long before your limit is reset	700
X-RateLimit-Period	Seconds	The total length of the rate limited period in	3600
X-RateLimit-Remaining	Integer	The number of requests you can still make	54999