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, full-text indexing, and geospatial 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 contains the service name along with the actual attribute name in the form <service-name>_<attribute-name> (for example 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 requested method. 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 information can be found in the body of the response.

Error Responses specific to /_api/v2/ endpoints

If an error response is received from the server endpoint, the Go SDK will create an error object that contains either the HTTP response error message or a generic error message.

An additional detailedResponse will be returned by the service that will contain the following fields:

If an error response is received from the server endpoint, the Java&trade SDK will throw an exception from the com.ibm.cloud.sdk.core.service.exception package. The base class for all exception classes is ServiceResponseException - that derives from RuntimeException - to handle any error response from the server. Here is a list about predefined exceptions and their corresponding statusCode and message content.

All service exceptions contain the following fields:

If an error response is received from the server endpoint, the Node SDK will create an Error object that contains either the HTTP response error message or a generic error message. In case of network problems the axios package will generate an Error object. This Error object is passed as the first parameter to the callback function, its failure describing content is as shown in the following table.

If an error response is received from the server endpoint, the Python SDK will throw an ApiException that includes more information about the cause of the failure. It provides the following details:

HTTP API requests may also not complete successfully due to error conditions in the network. This condition will cause IBM Cloudant request to fail.

An example would be an HTTP request timeout. In this case the request returns detailedResponse with only StatusCode - Result and RawResult elements will be nil.

Argument validation prevents invalid values and stops the request from being sent. This results in Result and RawResult objects being nil, and a returned error message with no status code or reason.

In all other cases, detailedResponse will be nil because it is returned only by IBM Cloudant Service.

In this case, an IOException will be thrown and will be wrapped in a RuntimeException.

Argument validation prevents invalid values and stops the request from being sent. Invalid argument values raise an IllegalArgumentException exception.

In this case, the status will be undefined and body content will be non-JSON formatted error description.

Argument validation prevents invalid values and stops the request from being sent. Invalid argument values raise an Error object containing a code field with the value ERR_INVALID_ARG_VALUE.

In this case, the requests package will raise specific exceptions for these problems.

Argument validation prevents invalid values and stops the request from being sent. Invalid argument values raise an 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.

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.

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

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

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: $ACCOUNT.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://$ACCOUNT.cloudant.com/db/doc" \
	-X PUT \
	-T doc.gzip \
	-H "Content-Encoding: gzip"

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.

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 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-Range
• Content-Type
• Etag
• Via
• X-Content-Type-Options
• X-Couch-Request-ID
• X-Cloudant-Action
• X-Cloudant-Backend
• X-Cloudant-Request-Class
• X-Frame-Options

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

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.

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-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 for 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 towards the instance's throughput capacity's budget.

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.

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.