IBM® Cloudant® for IBM Cloud® is a document-oriented database as a service (DBaaS). It stores data as documents in JSON format. It is built with scalability, high availability, and durability in mind. It comes with a wide variety of indexing options that include MapReduce, IBM Cloudant Query, and full-text indexing. The replication capabilities make it easy to keep data in sync between database clusters, desktop PCs, and mobile devices.

Detailed documentation is also available such as a Getting started tutorial, API overview documentation, tutorials, and guides.

If you intend to store sensitive information in an IBM® Cloudant® for IBM Cloud® database you must use client-side encryption to render data unreadable to Cloudant operators. For example for PCI DSS compliance you must encrypt the Primary Account Number (PAN) before sending a document containing it to the database.

This documentation describes the SDKs and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

This documentation describes the Java SDK and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

This documentation describes the Node SDK and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

This documentation describes the Python SDK and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

This documentation describes the Go SDK and examples. To see usage information and examples in your preferred SDK, select the language tab in the right pane.

The IBM Cloudant API uses an instance-specific endpoint URL for all regions. You can find your external endpoint by following these steps:

1. Go to the IBM Cloud dashboard and open an instance.
2. Click the Service credentials tab.
3. Click the chevron next to the service credentials to open the credentials pane.
4. Copy the value from the host field and prefix it with the https:// protocol. This value is the external endpoint.

For more information, see the Locating your service credentials tutorial.

Or you can copy your external endpoint by following these steps:

1. Go to the IBM Cloud dashboard and open an instance.
2. Under the Manage tab on the Overview page, see the External endpoint in the table.
3. Click Copy to copy the External endpoint. Paste the endpoint where you need your credentials.

A public endpoint looks something like these examples:

https://5lll032-dd12-536e-09b3-432fg9f07e78-bluemix.cloudantnosqldb.appdomain.cloud

or

https://5lll032-dd12-536e-09b3-432fg9f07e78-bluemix.cloudant.com

A private endpoint is one that is only accessible through a non-public network, like IBM's internal network. Private endpoints are available to customers who have the Dedicated Hardware plan.

You can access IBM Cloudant with IBM Cloud® Identity and Access Management (IAM) or IBM Cloudant legacy access controls. The choice between Use only IAM and Use both legacy credentials and IAM access control affects how credentials are delivered to your application when you bind and generate service credentials.

The Use only IAM option is preferred. Review Must I use Use only IAM or Use both legacy credentials and IAM? to help with making a decision.

IAM authentication

Access to IBM Cloudant is centrally controlled by IBM Cloud® Identity and Access Management (IAM), which provides a unified approach to managing user identities, and access control across your IBM Cloud® services and applications using the same set of credentials.

To work with the API, authenticate your application or service by including your IBM Cloud® IAM access token in API requests.

Cloudant legacy authentication

Legacy access controls are unique to IBM Cloudant, which means that accessing each service instance requires its own set of credentials. These credentials can be used with HTTP basic and cookie authentication. IBM Cloudant legacy API keys authenticate identically to username and password credentials but are generated and assigned differently. For more information, see the documentation about IBM Cloudant legacy API keys.

Additional authentication resources

• IBM Cloudant client libraries provide full integration with IAM's access controls and automatically retrieve an IAM access token when an appropriate IAM configuration is provided (for example, an IAM API key or IAM profile ID).
• View IBM Cloudant authentication documentation.

Authentication to this API's methods uses one of the following security schemes.

In this scenario, the configuration is defined with an external credentials file and an authenticator that is constructed by SDK's authenticator factory during client initialization. Using the external credentials file avoids hardcoded credentials within the application code.

The default name of the credentials file is ibm-credentials.env. It is expected to be located in either the current directory or in the user's home directory. The path and name of the file can be controlled by using the IBM_CREDENTIALS_FILE environment variable.

Cloudant configuration properties start with a chosen service name prefix that identifies your service. By default it is CLOUDANT.

If you would like to rename your Cloudant service from CLOUDANT, or use multiple services at the same time you must use your defined service name as the prefix for all of your Cloudant related configuration properties. You also must use the same service name at instantiating your service.

This way, each configuration property includes both the name of the service and the specific attribute, combined in a format like CLOUDANT_APIKEY.

It is not necessary to use a .env file. These properties can be set by using environment variables with the same name in the environment where the application is run.

In this scenario, authentication is configured by constructing an authenticator instance, supplying the configuration attributes programmatically, and then passing this instance to a client constructor.

If you are using the IBM Cloud App Service, IBM Cloud® Continuous Delivery or IBM Cloud starter kits then you can programmatically configure your SDK using the IBMCloudEnv tool to obtain the configuration information from bound services. The IBMCloudEnv tool is available for Go, Java&trade (Spring), Node.js, and Python.

IBM Cloudant operation uses standard HTTP response codes to indicate the status of the operation. HTTP response codes in the 2xx range indicate success. A 4xx range indicates a failure, and a 5xx range usually indicates an internal system error. More detailed error information is available in the body of the response.

For some HTTP requests, for example bulk operations, a 2xx response may indicate overall request success, but individual actions may have failed. For these cases the HTTP status code is insufficient to indicate success or failure and the caller must inspect the response body contents.

IBM Cloudant HTTP API requests may also fail due to external factors, for example, network errors. These kinds of errors may prevent the server receiving the request or the client receiving the HTTP response. As a result the error format is different in these cases.

The HTTP response headers may contain additional information useful for tracing errors.

When the Go SDK receives an error response from the server endpoint it returns a standard Go error. The Error() function of the error returns either the HTTP response error message or a generic error message.

In addition to an error SDK operations may also return a DetailedResponse with methods to retrieve additional information.

Other errors

HTTP API requests may also fail with other error conditions, for example, validation or networking issues.

For errors unrelated to the HTTP status code the SDK still returns a standard Go error. However, the DetailedResponse information is absent or limited.

An example would be an HTTP request that the server terminates when it exceeds a timeout. In this case the request returns a DetailedResponse with only a StatusCode. The Result and RawResult elements are nil.

Argument validation prevents some invalid values and the SDK does not send the request. This results in Result and RawResult being nil, and a returned error message with no status code or reason.

In all other cases, DetailedResponse is nil because there is no JSON error response from the IBM Cloudant Service.

When the Java SDK receives an error response from the server endpoint it throws a RuntimeException. Specifically a subclass of ServiceResponseException from the com.ibm.cloud.sdk.core.service.exception package. The specific subclass depends on the error encountered.

All ServiceResponseException types have methods to retrieve additional error information.

Other errors

HTTP API requests may also fail with other error conditions, for example, validation or networking issues.

For errors unrelated to the HTTP status code the SDK throws other RuntimeException types.

For example for many networking errors the SDK throws an IOException wrapped in a RuntimeException.

Argument validation prevents some invalid values and the SDK does not send the request. For these cases the SDK throws an IllegalArgumentException.

When the Node SDK receives an error response from the server endpoint it creates an Error that contains either the HTTP response error message or a generic error message. The Promise returned from the SDK operation rejects with this Error.

For HTTP response errors the properties of the of Error include additional information.

Other errors

HTTP API requests may also fail with other error conditions, for example, validation or networking issues.

For errors unrelated to the HTTP status code the SDK still rejects with an Error. However, the available error properties may be more limited.

For these errors message still provides a summary of the problem. There is no status defined since there is no HTTP response status code. The statusText or body contain additional information.

When an error prevents the request reaching the service the Error code property may be useful.

An example is argument validation that prevents some invalid values and the SDK does not send the request. Invalid argument values reject with an Error object containing a code field with the value ERR_INVALID_ARG_VALUE.

When the Python SDK receives an error response from the server endpoint it raises a standard Python Exception. For HTTP response errors the subclass is ApiException from the ibm_cloud_sdk_core module. The ApiException includes more information about the cause of the failure.

Use the json() method of the http_response attribute to obtain even more detailed error information.

Other errors

HTTP API requests may also fail with other error conditions, for example, validation or networking issues.

For errors unrelated to the HTTP status code the SDK still raises an Exception. However, the available error properties are different.

Networking errors and issues like timeouts raise a requests.RequestException. Consult the requests documentation for details of the available subclasses for specific connection related error conditions.

Argument validation prevents some invalid values and the request is not sent. Invalid argument values raise a ValueError exception.

You can monitor API activity within your account by using the IBM Cloud® Activity Tracker service. An event is generated for most of the API endpoints when they are called, and you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method. For methods that don't list any events, no events are generated.

For more information about how to track IBM Cloudant activity, see Audit logging.

IBM Cloudant uses HTTP. Set the correct HTTP request headers and process the response headers inline with the HTTP specification. 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, be as specific as possible for your client environment.

IBM Cloudant SDKs handle required headers automatically. The SDKs also allow for setting some headers as part of the request options without needing to use custom header code.

You can pass additional request header parameters in all requests or in a single request to the service.

To pass header parameters in a single curl request, use the -H option.

To pass header parameters with every request, use the SetDefaultHeaders method of the service object.

To pass header parameters in a single request, use SetHeaders to include the headers in the options struct before calling the operation.

You can pass request header parameters in all requests or in a single request to the service.

To pass header parameters with every request, use the setDefaultHeaders method of the service object.

To pass header parameters in a single request, use the addHeader method as a modifier before you execute the request.

You can pass request header parameters in all requests or in a single request to the service.

To pass header parameters with every request, specify the set_default_headers method of the service object.

To pass header parameters in a single request, include headers as a dict in the request.

You can pass request header parameters in all requests or in a single request to the service.

To pass header parameters with every request, specify the set_default_headers method of the service object.

To pass header parameters in a single request, include headers as a dict in the request.

Additional supported HTTP request headers are:

• Accept
• Accept-Encoding
• Content-Type
• Content-Encoding
• If-None-Match
• Range
• X-Request-ID

Accept

The Accept header specifies the list of potential data types returned by the server that the client accepts. The format is a list of one or more MIME types, 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 the client accepts any type.

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

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

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.

IBM Cloudant SDKs set this header automatically except for requests where the user controls the content type, for example, attachments.

Example of sending a request without an explicit Accept header, or when you specify */*.

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

Example of a returned header when the client accepts all formats.

The returned content type is text/plain even though the information 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

Example request that explicitly specifies the Accept header.

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

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

Accept-Encoding

The Accept-Encoding header specifies the server encoding of the response body the client accepts. The supported values are:

• gzip
• identity

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.

IBM Cloudant SDKs set this header and compress request bodies automatically.

You can also send compressed request bodies using gzip and curl.

Example creating a gzipped document.

echo '{"foo":"bar"}' | gzip > doc.gzip

Example using the gzipped document in a curl request.

curl "https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud/db/doc" \
	-X PUT \
	-T doc.gzip \
	-H "Content-Encoding: gzip"

Content-Type

The Content-Type header specifies the content type of the HTTP request body. 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.

If-None-Match

The If-None-Match header is optional. You might send it to determine whether a document changed 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 changed, you get a normal 200 response, provided the document still exists and no other errors occurred.

Range

The Range header specifies the parts of an attachment that the server should return. Several parts can be requested at the same time in one Range header, and the server may send back these ranges in a multipart document. If the server sends back ranges, it uses the status line 206 Partial Content for the response.

X-Request-ID

Assign a UUIDv4 (random) to a request for tracing. If the supplied X-Request-ID header value is a valid UUIDv4 it is also returned in the response X-Request-ID header. If the X-Request-ID is not set on a request or the supplied value is not a valid UUIDv4 then the server generates a valid value and returns it in the response X-Couch-Request-ID header.

The server returns response headers when you receive 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:

• Cache-Control
• Content-Encoding
• Content-Length
• Content-Range
• Content-Type
• Etag
• Via
• X-Cloudant-Action
• X-Cloudant-Backend
• X-Cloudant-Request-Class
• X-Content-Type-Options
• X-Couch-Request-ID
• X-Frame-Options
• X-Request-ID

The IBM Cloudant design document API and its functions return HTML (for example as part of a show or list). After which, you can include custom HTTP headers through the headers field of the return object.

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-Encoding

Indicates the encoding of the response body as negotiated by the Accept-Encoding request header.

Content-Length

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

Content-Range

The Content-Range header specifies where in the full document's attachment a partial content belongs. The value is in the form of bytes <range>/<total content length>. The Range request header is required to specify the partial content to be returned.

Content-Type

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, 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 random numbers that change on every request.

Via

A name of an individual reverse proxy server that processed the request.

X-Cloudant-Action

An auditing event's action name generated for the request.

X-Cloudant-Backend

A name of an individual backend server that processed the request.

X-Cloudant-Request-Class

A request class assigned to the request that count toward the instance's throughput capacity's budget.

X-Content-Type-Options

The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the MIME types advertised in the Content-Type headers should be followed and not be changed. This is a security feature to block content sniffing that could transform non-executable MIME types into executable MIME types. By default Cloudant returns X-Content-Type-Options: nosniff that blocks a request if the request destination is of type style and the MIME type is not text/css, or of type script and the MIME type is not a JavaScript MIME type.

X-Couch-Request-ID

A unique identifier generated by the server if the request did not have a valid X-Request-ID header.

X-Frame-Options

The X-Frame-Options is a response header that controls whether an HTTP response can be embedded in a <frame>, <iframe> or <object>. This is a security feature to help against clickjacking. Cloudant returns X-Frame-Options: DENY by default.

X-Request-ID

This header contains a UUIDv4 value matching the one supplied on the request. If a value was not supplied then the server assigns a UUIDv4 in the X-Couch-Request-ID response header.

Certain API endpoints have a limit on results returned per page to avoid performance issues. The sections below describe the options available and list the endpoints you can use them on.

The following endpoints have the limit and skip parameters which allow you to define how many documents you would like to see on a page, and the offset into the range you want to start the page from, but this pattern gets progressively slower the larger the value of skip gets. There are a couple of options which are more efficient than using the limit/skip pattern: either fetch one extra document, and use this document's id as the startKey of your request for the next page of results ("fetch one document too many"); or append \u0000 to the startKey, using the last id of the last document from your previous page of results ("the \u0000 trick").

The following endpoints have the Limit and Skip parameters which allow you to define how many documents you would like to see on a page, and the offset into the range you want to start the page from, but this pattern gets progressively slower the larger the value of Skip gets. There are a couple of options which are more efficient than using the Limit/Skip pattern: either fetch one extra document, and use this document's ID as the StartKey of your request for the next page of results ("fetch one document too many"); or append \u0000 to the StartKey, using the last ID of the last document from your previous page of results ("the \u0000 trick").

• GET /{db}/_all_docs
• POST /{db}/_all_docs
• GET /{db}/_partition/{partition_key}/_all_docs
• POST /{db}/_partition/{partition_key}/_all_docs
• GET /{db}/_design/{ddoc}/_view/{view}
• POST /{db}/_design/{ddoc}/_view/{view}
• GET /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}
• POST /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}

• postAllDocs
• postPartitionAllDocs
• postView
• postPartitionView

• post_all_docs
• post_partition_all_docs
• post_view
• post_partition_view

• PostAllDocs
• PostPartitionAllDocs
• PostView
• PostPartitionView

You can find examples and more explanation for both tricks in the Cloudant docs:

• Fetch one document too many for _all_docs
• The \u0000 trick for _all_docs
• The \u0000 trick for views

We recommend to use "the \u0000 trick" over "fetch one document too many".

The following endpoints use bookmarks as the key to access the next page of results from the result set. If you want to learn about the usage of bookmarks we recommend reading how IBM Cloudant bookmarks work.

• POST /{db}/_find
• POST /{db}/_partition/{partition_key}/_find
• GET /{db}/_design/{ddoc}/_search/{index}
• POST /{db}/_design/{ddoc}/_search/{index}
• GET /{db}/_partition/{partition_key}/_design/{ddoc}/_search/{index}
• POST /{db}/_partition/{partition_key}/_design/{ddoc}/_search/{index}

• postFind
• postPartitionFind
• postSearch
• postPartitionSearch

• post_find
• post_partition_find
• post_search
• post_partition_search

• PostFind
• PostPartitionFind
• PostSearch
• PostPartitionSearch

Rate limits for API requests are enforced on a per-service-instance basis. If the number of requests for a particular request class (read, write or global query) reaches the limit within the given time window, no further requests of that class are accepted until the next time window.

You can view your usage by using the Retrieve the current provisioned throughput capacity consumption API or the IBM Cloudant dashboard. IBM Cloudant does return an x-cloudant-request-class response header related to limiting.

x-cloudant-request-class response header returns the following request classes: read, write, global query, or unlimited.

If you want to learn more about these request classes, see the Request classes documentation.

A 429 HTTP status code indicates that the rate limit has been exceeded.

The number of allowed requests varies by request class. The reference information for each endpoint and method specifies the request class that applies to the request. The rate limit for each request class is determined by the account plan.

Most requests and responses to and from IBM® Cloudant® for IBM Cloud® use JavaScript Object Notation (JSON) for formatting the content and structure of the data and responses.

In IBM Cloudant databases, the JSON object is used to represent various structures, including all documents in a database.

Parsing JSON into a JavaScript object is supported through the JSON.parse() function in JavaScript, or through various libraries that perform the parsing of the content into a JavaScript object for you. Libraries for parsing and generating JSON are available for many major programming languages.

JSON is used because it's the simplest and easiest solution for working with data that uses a web browser. As a result, JSON structures can be evaluated and used as JavaScript objects within the web browser environment. JSON also integrates with the server-side JavaScript used within IBM Cloudant. JSON documents are always UTF-8 encoded.

Be careful to follow these guidelines:

• Your JSON structures are valid.
• You normalize strings in JSON documents retrieved from IBM Cloudant.

JSON supports the same basic types that are supported by JavaScript: numbers, strings, Booleans, arrays, and objects.

Numbers can be integer or floating point values.

Example of a number in JSON format

123

Strings must be enclosed by double quotation marks. Strings support Unicode characters and escaping a backslash.

Example of a string in JSON format

"A String"

A true or false value.

Example of a boolean in JSON format

{
  "value": true
}

A list of values enclosed in brackets. The values that are enclosed can be any valid JSON.

Example of an array in JSON format

[
    "one",
    2,
    "three",
    [],
    true,
    {
        "foo":
        "bar"
    }
]

Example of an array in JSON format (linear)

[ "one", 2, "three", [], true, { "foo": "bar" } ]

A set of key-value pairs, such as an associative array, or a hash. The key must be a string, but the value can be any of the supported JSON values.

Example of a JSON object

{
    "servings" : 4,
    "subtitle" : "Easy to make in advance, and then cook when ready",
    "cooktime" : 60,
    "title" : "Chicken Coriander"
}

A basic logging facility is provided by the Go core library with levels Error, Info, Warn, and Debug. If Debug level is enabled, it displays HTTP request and response messages and retry attempts.

The Go core library also defines a Logger interface, where you can supply your own logging implementation. For example, you can direct the log messages to a file instead of the console.

The logging detail level can be configured by using the HttpConfigOptions class.

The SDK is using debug package for logging. In order to see the log output, set the environment variable DEBUG including the wanted log level.

To enable logging, import the logging package and then setting the log level to DEBUG.