Payload Compression

All endpoints in the v2 REST API support gzip compression for both request and response payloads. Most client side frameworks have built-in support for gzip encoding as well. Compressing API payloads can improve an application's performance and to reduce bandwidth consumption by sending and receiving smaller payloads, something that is especially important for mobile applications and low bandwidth connections. 

HTTP headers for compressed payloads

Use the following HTTP headers to request a gzip compressed payload from the API:

Method Header to request a compressed response payload Header to use if sending compressed request payload
GET

Accept-Encoding: gzip

  N/A
PUT/POST Accept-Encoding: gzip Content-Encoding: gzip

bidirection api compression flow

Response codes

Code Code Description
200 Request was successful
400

Bad request; the payload format does not match the Content-Encoding value.

406

Not acceptable; Unsupported Accept-Encoding type.

Accept-Encoding must be gzip; identity encoding is accepted unless specified as

identity;q=0   OR *;q=0

415 Invalid Content-Encoding type. API only supports gzip.

What to expect when using compression

Using compression will reduce the size of JSON payloads larger than 100 Bytes. There is a cost in response time to either compress or decompress the payload. Below is a table showing representative gzip processing time for JSON payloads up to 10,000,000 bytes. Payloads of the same size but with differing content will have varied processing times.

JSON payload in Bytes Coddocdoc Gzip processing time (ms)
100 0
1,000 0
10,000 0
100,000 1
1,000,000 19
10,000,000 91

Android code sample

HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.addRequestProperty("Accept", "application/json");
connection.addRequestProperty("Authorization", "Bearer " + oAuthToken);
connection.addRequestProperty("Accept-Encoding", "gzip");
connection.setRequestMethod(method);
connection.connect();

int responseCode = connection.getResponseCode();

InputStream inputStream = null;
if (responseCode == HttpStatus.SC_OK || responseCode == HttpStatus.SC_CREATED || responseCode == HttpStatus.SC_ACCEPTED) {
inputStream = connection.getInputStream();

if ("gzip".equals(connection.getContentEncoding())) {
inputStream = new GZIPInputStream(inputStream);
}
} else {
inputStream = connection.getErrorStream();
}
 

iOS code sample

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:URL];
[request setValue:@"gzip" forHTTPHeaderField:@"Accept-Encoding"];

JavaScript sample

ajax=new XMLHttpRequest();
ajax.setRequestHeaders('accept-encoding','gzip');
ajax.setRequestHeaders('content-encoding','gzip');