HTTP

Important: All Cloudant documentation has moved to the IBM Bluemix platform. You can find the new content here, and the HTTP topic in particular here.

Content on this page will no longer be updated (Jan 31st, 2017).

This section provides details of the HTTP Headers and HTTP Status Codes you need to know when using Cloudant.

HTTP Headers

Because Cloudant uses HTTP for all external communication, you need to ensure that the correct HTTP request headers are supplied and processed on retrieval. This is to ensure 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. Where possible, you should be as specific as possible.

Request headers

The supported HTTP request headers include:

Accept
GET /recipes HTTP/1.1
Host: <account>.cloudant.com
Accept: */*
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: 227
Cache-Control: must-revalidate

Specifies the list of accepted data types to be returned by the server (i.e. that are accepted/understandable by the client). The format should be a list of one or more MIME types, separated by colons.

For the majority of requests the definition should be for 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 */* MIME type is assumed (i.e. client accepts all formats).

GET /recipes HTTP/1.1
Host: <account>.cloudant.com
Accept: application/json
Server: CouchDB/1.0.2 (Erlang OTP/R14B)
Date: Thu, 13 Jan 2011 13:40:11 GMT
Content-Type: application/json
Content-Length: 227
Cache-Control: must-revalidate

The use of Accept in queries to 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 using the Accept header, Cloudant will honor the specified type in the Content-type header field returned. For example, if you explicitly request application/json in the Accept of a request, the returned HTTP headers will use the value in the returned Content-type field.

Content-Type

Specifies the content type of the information being supplied within the request. The specification uses MIME type specifications. For the majority of requests this is JSON (application/json). For some settings the MIME type is plain text. When uploading attachments it should 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
# create gzipped document
echo '{"foo":"bar"}' | gzip >doc.gzip
# create the document in the database
curl https://$ACCOUNT.cloudant.com/db/doc -X PUT -T doc.gzip -H 'Content-Encoding: gzip'
PUT /db/doc HTTP/1.1
HOST: <account>.cloudant.com
Content-Encoding: gzip

The Content-Encoding header specifies the encoding of the request body. Supported values are gzip and deflate. If the header is used, the request body must be compressed with gzip or deflate accordingly.

If-None-Match

This header can optionally be sent to find out whether a document has been modified since it was last read or updated. The value of the If-None-Match header should 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 will not have a body. If not, you should get a normal 200 response, provided the document still exists and no other errors occur.

Response Headers

Response headers are returned by the server when sending back content and include a number of different header fields, many of which are standard HTTP response header and have no significance to how Cloudant operates. The list of response headers important to Cloudant are as follows.

The supported HTTP response headers include:

The Cloudant design document API and the functions when returning HTML (for example as part of a show or list) enable you to include custom HTTP headers through the headers field of the return object.

Cache-Control

The cache control HTTP response header provides a suggestion for client caching mechanisms on how to treat the returned information. Cloudant typically returns the must-revalidate, which indicates that the information should be revalidated if possible. This is used to ensure that the dynamic nature of the content is correctly updated.

Content-Length

The length (in bytes) of the returned content.

Content-Type field

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), and this is explicitly stated in the returned Content-type, as text/plain;charset=utf-8.

Etag

The Etag HTTP header field is used to show the revision for a document or the response from a show function. 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 or lists, since the ETags returned from those requests are just random numbers that change on every request.

HTTP Status Codes

With the interface to Cloudant working through HTTP, error codes and statuses are reported using a combination of the HTTP status code number, and corresponding data in the body of the response data.

A list of the error codes returned by Cloudant and generic descriptions of the related errors are as follows. The meaning of different status codes for specific request types are provided in the corresponding API call reference.

{
  "error":"not_found",
  "reason":"no_db_file"
}