How HTTP works with IBM Cloudant

Learn details about the HTTP headers you need to know when you use IBM® Cloudant® for IBM Cloud®.

HTTP headers

Because IBM Cloudant uses HTTP for all external communication, you need to ensure that the correct HTTP request headers are supplied and processed on retrieval. This course of action ensures that you get the correct format and encoding. Different environments and clients are more or less strict on the effect of these HTTP headers, especially when they are not present. To reduce the likelihood of problems or unexpected behavior, you must be as specific as possible.

Request headers

The supported HTTP request headers are shown in the following list:

Accept
Content-Type
Content-Encoding
If-None-Match

Accept

The Accept header specifies the list of potential data types that are returned by the server that would be accepted and understood by the client. The format is a list of one or more MIME types, which are separated by colons.

For the most requests, the accepted list must include JSON data (application/json).

For attachments, you can either specify the MIME type explicitly, or use */* to specify that all file types are supported.

If the Accept header is not supplied, then the server assumes the */* MIME type, which means that the client accepts all formats.

See the following example of sending a request without an explicit Accept header, or when you specify */*:

GET /recipes HTTP/1.1
Host: username.cloudant.com
Accept: */*

See the following example of a returned header when the client is assumed to accept all formats.

The returned content type is text/plain even though the information that is returned by the request is in JSON format.

Server: CouchDB/1.0.2 (Erlang OTP/R14B)
Date: Thu, 13 Jan 2011 13:39:34 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: #7
Cache-Control: must-revalidate

The use of Accept in queries to IBM Cloudant is not required, but is highly recommended as it helps to ensure that the data returned can be processed by the client.

If you specify a data type that uses the Accept header, IBM Cloudant honors the specified type in the Content-type header field of responses. For example, if you explicitly request application/json in the Accept of a request, the returned HTTP headers use this value in the returned Content-type field.

See the following example request that explicitly specifies the Accept header:

GET /recipes HTTP/1.1
Host: username.cloudant.com
Accept: application/json

See the following example of the headers returned in response, including the application/json content type:

Server: CouchDB/1.0.2 (Erlang OTP/R14B)
Date: Thu, 13 Jan 2011 13:40:11 GMT
Content-Type: application/json
Content-Length: #7
Cache-Control: must-revalidate

Content-Type for request headers

The Content-Type header specifies the content type of the information that is supplied within the request. The specification uses MIME type specifications. For most requests, the content type is JSON (application/json).

For some settings, the MIME type is plain text.

In particular, when you upload attachments the type must be the corresponding MIME type for the attachment or binary (application/octet-stream).

The use of the Content-Type on a request is highly recommended.

Content-Encoding

The Content-Encoding header specifies the encoding of the request body. The supported value is gzip. If the header is used, the request body must be encoded with the corresponding format.

See the following example of creating a compressed (gzipped) request body:

# create gzipped document
echo '{"foo":"bar"}' | gzip > doc.gzip

See the following example of sending a gzip-encoded request body to create a document by using HTTP:

PUT /db/doc HTTP/1.1
HOST: example.cloudant.com
Content-Encoding: gzip

See the following example of sending a gzip-encoded request body to create a document by using the command line:

curl "https://example.cloudant.com/db/doc" \
	-X PUT \
	-T doc.gzip \
	-H "Content-Encoding: gzip"

By default, the SDKs compress the request body.

If-None-Match

The If-None-Match header is optional. You might send it to determine whether a document was modified since it was last read or updated. The value of the If-None-Match header must match the last Etag value received. If the value matches the current revision of the document, the server sends a 304 Not Modified status code, and the response itself has no body.

If the document was modified, you get a normal 200 response, provided the document still exists and no other errors occurred.

Response headers

Response headers are returned by the server when you send back content. They include a number of different fields. Many of the fields are standard HTTP response headers and have no significance regarding how IBM Cloudant operates. The supported HTTP response headers that are important to IBM Cloudant are as shown in the following list.

Cache-Control
Content-Length
Content-Type
Etag

Cache-Control

The Cache-Control HTTP response header provides a suggestion for the client cache mechanisms on how to treat the returned information. IBM Cloudant typically returns the must-revalidate value, which indicates that the information must be revalidated if possible. Revalidation ensures that the dynamic nature of the content is correctly updated.

Content-Length

The Content-Length header reports the length in bytes of the returned content.

Content-Type for response headers

The Content-Type header specifies the MIME type of the returned data. For most request, the returned MIME type is text/plain. All text is encoded in Unicode (UTF-8), which is explicitly stated in the returned Content-Type as text/plain;charset=utf-8.

`Etag`

The Etag header is used to show the revision for a document. For documents, the value is identical to the revision of the document. The value can be used with an If-None-Match request header to get a 304 Not Modified response if the revision is still current.

ETags cannot currently be used with views, since the ETags returned from those requests are random numbers that change on every request.