Cloudant | IBM Cloud API Docs

Introduction

Last updated: 2023-05-24

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 code examples on this tab use the IBM Cloudant SDK for Java&trade.

Gradle

implementation 'com.ibm.cloud:cloudant:0.+'

Maven

Maven installation instructions

GitHub

https://github.com/ibm/cloudant-java-sdk

The code examples on this tab use the IBM Cloudant SDK for Node.js.

Installation

npm install --save @ibm-cloud/cloudant

GitHub

https://github.com/ibm/cloudant-node-sdk

The code examples on this tab use the IBM Cloudant SDK for Python.

Installation

pip3 install ibmcloudant

GitHub

https://github.com/ibm/cloudant-python-sdk

The code examples on this tab use the IBM Cloudant SDK for Go.

Installation

go get -u github.com/IBM/cloudant-go-sdk/cloudantv1

GitHub

https://github.com/ibm/cloudant-go-sdk

Endpoint URLs

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

Go to the IBM Cloud dashboard and open an instance.
Click the Service credentials tab.
Click the chevron next to the service credentials to open the credentials pane.
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:

Go to the IBM Cloud dashboard and open an instance.
Under the Manage tab on the Overview page, see the External endpoint in the table.
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.

Authentication

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.

Security scheme

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

Basic

Valid only for IBM Cloudant legacy authentication (including legacy IBM Cloudant API keys).

Authenticates with a Authorization: Basic {credentials} header where credentials is the Base64 encoding of your username and password joined by a single colon :.

Attribute

Value

Type
HTTP
Scheme
Basic

Cookie

Valid only for IBM Cloudant legacy authentication (including legacy IBM Cloudant API keys).

Login session cookies can be created via the POST /_session endpoint and returned in the standard Set-Cookie header. This AuthSession cookie can be stored and returned to the server in the Cookie header on subsequent requests. This process is handled automatically by IBM Cloudant's SDKs and other cookie aware HTTP clients like browsers.

Attribute

Value

Type
API Key
In
Cookie
Name
AuthSession

IAM

Valid only for Cloud Identity and Access Management authentication.

Authenticates with a Authorization: Bearer {access_token} header where access_token is calculated from an appropriate IAM configuration (for example from an IAM API key, or IAM profile ID). This process is handled automatically by IBM Cloudant's SDKs.

Attribute

Value

Type
HTTP
Bearer format
JWT
Scheme
Bearer

Authentication with external configuration

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.

Variable guide for the authentication code samples

Table 1. Variable signing guide
Attribute name	Description
`{apikey}`	IAM API key
`{username}`	Cloudant username
`{password}`	Cloudant password
`{url}`	URL of Cloudant instance
`{service-name}`	Chosen service name of your Cloudant instance. Same as the prefix of your configuration properties. Default value is `CLOUDANT`.

SDK managing the IAM token. Replace {apikey} and {url}.

{service-name}_URL={url}
{service-name}_APIKEY={apikey}

import com.ibm.cloud.cloudant.v1.Cloudant;

Cloudant service = Cloudant.newInstance("{service-name}");

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({
    serviceName: '{service-name}'
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance(service_name="{service-name}")

import (
    "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

service, err := cloudantv1.NewCloudantV1UsingExternalConfig(
    &cloudantv1.CloudantV1Options{
        ServiceName: "{service-name}",
    },
)

SDK managing session cookie.

{service-name}_AUTH_TYPE=COUCHDB_SESSION
{service-name}_URL={url}
{service-name}_USERNAME={username}
{service-name}_PASSWORD={password}

import com.ibm.cloud.cloudant.v1.Cloudant;

Cloudant service = Cloudant.newInstance("{service-name}");

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({
    serviceName: '{service-name}'
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance(service_name="{service-name}")

import (
    "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

service, err := cloudantv1.NewCloudantV1UsingExternalConfig(
    &cloudantv1.CloudantV1Options{
        ServiceName: "{service-name}",
    },
)

Basic authentication.

{service-name}_AUTH_TYPE=BASIC
{service-name}_URL={url}
{service-name}_USERNAME={username}
{service-name}_PASSWORD={password}

import com.ibm.cloud.cloudant.v1.Cloudant;

Cloudant service = Cloudant.newInstance("{service-name}");

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({
    serviceName: '{service-name}'
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance(service_name="{service-name}")

import (
    "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

service, err := cloudantv1.NewCloudantV1UsingExternalConfig(
    &cloudantv1.CloudantV1Options{
        ServiceName: "{service-name}",
    },
)

Programmatic authentication

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.

SDK managing the IAM token.

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

IamAuthenticator authenticator = new IamAuthenticator.Builder()
    .apikey("{apikey}")
    .build();

Cloudant service = new Cloudant(Cloudant.DEFAULT_SERVICE_NAME, authenticator);

service.setServiceUrl("{url}");

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const { IamAuthenticator } = require('ibm-cloud-sdk-core');

const authenticator = new IamAuthenticator({
    apikey: '{apikey}'
});

const service = new CloudantV1({
    authenticator: authenticator
});

service.setServiceUrl('{url}');

from ibmcloudant.cloudant_v1 import CloudantV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')

service = CloudantV1(authenticator=authenticator)

service.set_service_url('{url}')

import (
    "github.com/IBM/cloudant-go-sdk/cloudantv1"
    "github.com/IBM/go-sdk-core/core"
)

authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
}

service, err := cloudantv1.NewCloudantV1(
    &cloudantv1.CloudantV1Options{
        URL:           "{url}",
        Authenticator: authenticator,
    },
)
if err != nil {
    panic(err)
}

SDK managing session cookie.

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.sdk.core.security.Authenticator;
import com.ibm.cloud.cloudant.security.CouchDbSessionAuthenticator;

Authenticator authenticator = CouchDbSessionAuthenticator.newAuthenticator("{username}", "{password}");

Cloudant service = new Cloudant(Cloudant.DEFAULT_SERVICE_NAME, authenticator);

service.setServiceUrl("{url}");

const { CloudantV1, CouchdbSessionAuthenticator } = require('@ibm-cloud/cloudant');

const authenticator = new CouchdbSessionAuthenticator({
    username: '{username}',
    password: '{password}'
});

const service = new CloudantV1({
    authenticator: authenticator
});

service.setServiceUrl('{url}');

from ibmcloudant.cloudant_v1 import CloudantV1
from ibmcloudant import CouchDbSessionAuthenticator

authenticator = CouchDbSessionAuthenticator('{username}', '{password}')

service = CloudantV1(authenticator=authenticator)

service.set_service_url('{url}')

import (
    "github.com/IBM/cloudant-go-sdk/cloudantv1"
    "github.com/IBM/cloudant-go-sdk/auth"
)

authenticator, err := auth.NewCouchDbSessionAuthenticator(
    "{username}",
    "{password}",
)
if err != nil {
    panic(err)
}

service, err := cloudantv1.NewCloudantV1(
    &cloudantv1.CloudantV1Options{
        URL:           "{url}",
        Authenticator: authenticator,
    },
)
if err != nil {
    panic(err)
}

Basic authentication.

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.sdk.core.security.BasicAuthenticator;

BasicAuthenticator authenticator = new BasicAuthenticator.Builder()
    .username("{username}")
    .password("{password}")
    .build();

Cloudant service = new Cloudant(Cloudant.DEFAULT_SERVICE_NAME, authenticator);

service.setServiceUrl("{url}");

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const { BasicAuthenticator } = require('ibm-cloud-sdk-core');

const authenticator = new BasicAuthenticator({
    username: '{username}',
    password: '{password}'
});

const service = new CloudantV1({
    authenticator: authenticator
});

service.setServiceUrl('{url}');

from ibmcloudant.cloudant_v1 import CloudantV1
from ibm_cloud_sdk_core.authenticators import BasicAuthenticator

authenticator = BasicAuthenticator('{username}', '{password}')

service = CloudantV1(authenticator=authenticator)

service.set_service_url('{url}')

import (
    "github.com/IBM/cloudant-go-sdk/cloudantv1"
    "github.com/IBM/go-sdk-core/core"
)

authenticator, err := core.NewBasicAuthenticator(
    "{username}",
    "{password}",
)
if err != nil {
    panic(err)
}

service, err := cloudantv1.NewCloudantV1(
    &cloudantv1.CloudantV1Options{
        URL:           "{url}",
        Authenticator: authenticator,
    },
)
if err != nil {
    panic(err)
}

Error handling

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.

List of HTTP codes

HTTP Code	Meaning
`200 - OK`	Request completed successfully.
`201 - Created`	Resource that is created or updated successfully. The resource could be a database or a document, for example.
`202 - Accepted`	Request was accepted, but the quorum for the operation was not met.
`304 - Not Modified`	The content that is requested was not modified. This error is used with the ETag system to identify the version of information returned.
`400 - Bad Request`	Bad request structure. The error can indicate an error with the request URL, path, or headers. Differences in the supplied MD5 hash and content also trigger this error, as this error might indicate message corruption.
`401 - Unauthorized`	The item requested was not available with the supplied authorization, or authorization was not supplied.
`402 - Payment required`	Either the data quota on the Lite plan was exceeded, or the account is in arrears. You can delete data or upgrade to the Standard plan, or bring the account up to date.
`403 - Forbidden`	The requested item or operation is forbidden.
`404 - Not Found`	The requested resource could not be found. The content includes further information as a JSON object, if available. The structure contains two keys, `error` and `reason`, similar to the following example: `{ "error":"not_found", "reason":"no_db_file" }`
`405 - Resource Not Allowed`	A request was made by using an invalid HTTP request type for the URL requested. For example, you requested a `PUT` when a `POST` is expected. Errors of this type can also be triggered by invalid URL strings.
`406 - Not Acceptable`	The requested content type is not supported by the server.
`408 - Request Timeout`	Timeout during reading client request.
`410 - Gone`	The requested resource is no longer available.
`409 - Conflict`	Request resulted in an update conflict. The two most common causes are: 1. Trying to update or delete a document without providing a revision. 2. The latest revision of the document on the server changed in between a fetch and an update.
`412 - Precondition Failed`	The request headers from the client and the capabilities of the server do not match. Alternatively, a request to create a database was denied because the database exists.
`413 - Request Entity Too Large`	The request size exceeded the limit for the IBM Cloudant API.
`415 - Bad Content Type`	The content types supported and the content type of the information that was requested or submitted. The error indicates that the content type is not supported.
`416 - Requested Range Not Satisfiable`	The range that is specified in the request header cannot be satisfied by the server.
`429 - Too Many Requests`	The user sent too many requests in a specific amount of time. More information is available in the corresponding RFC 6585.
`500 - Internal Server Error`	The request could not be completed by the server. It could be due to an internal error or in some cases invalid data in the request. Alternatively, a replication was canceled while in progress.
`502 - Bad Gateway`	The server while acting as a gateway or proxy, received an invalid response from the upstream server.
`503 - Service Unavailable`	The request could not be processed. Seeing this response might indicate a misspelled IBM Cloudant account name.
`504 - Gateway Timeout`	Timeout when the server is acting as a gateway and cannot get a response in time.

Error response

Name	Description
error `string`	the error message returned in the response
reason `string`	a more detailed description about the cause of the failure
caused_by (optional) `string`	the cause of the error

Error Responses specific to /_api/v2/ endpoints

Name	Description
code `integer`	HTTP error code
error `string`	a more detailed description about the cause of the failure

Name	Description
message `string`	detailed description about the cause of the failure

Error Response

{
  "error":"bad_request",
  "reason":"invalid UTF-8 JSON"
}

Error Responses specific to /_api/v2/ endpoints

{
    "code": 404,
    "error": "Could not find Cloudant user"
}

{
    "message": "The method is not allowed for the requested URL."
}

Code example

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:

Field	Description
StatusCode	HTTP response status code
Result	JSON error response object unmarshalled as `map[string]interface{}`
RawResult	raw non-JSON error response object as `[]byte`

Example error handling

_, detailedResponse, err := // Invoke a Cloudant method request
if err != nil {
    if (detailedResponse != nil) {
      fmt.Println("Error status code: ", detailedResponse.StatusCode)
      fmt.Println("Error message:     ", err.Error())
      errorMap, ok := detailedResponse.GetResultAsMap(); if ok {
        fmt.Println("Reason:          ", errorMap["reason"])
      }
    } else {
      // Handle other error conditions
      fmt.Println("Error message: ", err.Error())
    }
  }

Code example

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.

Exception	Status Code and default error message
ServiceResponseException	Base class for all exceptions
BadRequestException	`400` Bad Request
UnauthorizedException	`401` Unauthorized
ForbiddenException	`403` Forbidden
NotFoundException	`404` Not found
ConflictException	`409` Conflict
UnsupportedException	`415` Unsupported media type
InternalServerErrorException	`500` Internal server error
IllegalArgumentException	An invalid argument was passed to the method.

All service exceptions contain the following fields:

Field	Description
statusCode	HTTP response status code
message	the error message returned in the response
debuggingInfo	a `Map<String, Object>` which contains the unmarshalled error response object if a JSON error response is returned. This will provide more information beyond the error message.

Example error handling

import com.ibm.cloud.sdk.core.service.exception.BadRequestException;
import com.ibm.cloud.sdk.core.service.exception.NotFoundException;
import com.ibm.cloud.sdk.core.service.exception.ServiceResponseException;
import com.ibm.cloud.sdk.core.service.exception.UnauthorizedException;
import com.ibm.cloud.sdk.core.service.exception.IllegalArgumentException;

try {
  // Invoke a Cloudant method request
} catch (BadRequestException e) {
  // Handle Bad Request (400) exception
} catch (UnauthorizedException e) {
  // Handle Unauthorized (401) exception
} catch (NotFoundException e) {
  // Handle Not Found (404) exception
} catch (ServiceResponseException se) {
  System.out.println("Service returned status code "
    + se.getStatusCode() + ": " + se.getMessage());
  System.out.println("Detailed error info: " + se.getDebuggingInfo().getOrDefault("reason", "")););
} catch (RuntimeException re) {
  // Handle other error conditions
  System.out.println("Unexpected Exception:\n" + re.getMessage());
} catch (IllegalArgumentException iae) {
  // Handle invalid argument value
  System.out.println("Invalid argument value:\n" + iae.getMessage());
}

Code example

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.

Field	Description
status	HTTP response status code
statusText	a text description of the status code
message	generic error message
body	the error response body as text

Example error handling

service.CloudantMethod(params)
  .then((response) => {
    // ...handle successful response...
  })
  .catch(error => {
    if (error.code !== undefined && error.code === "ERR_INVALID_ARG_VALUE") {
      // The request was not sent, so there is no error status code, text and body
      console.log("Invalid argument value: \n" + error.message);
    } else {
      console.log("Error status code: " + error.status);
      console.log("Error status text: " + error.statusText);
      console.log("Error message:     " + error.message);
      console.log("Error details:     " + error.body)
    }
  });

Code example

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:

Field	Description
code	HTTP response status code
message	the error message returned in the response
reason	a more detailed description about the cause of the failure

Example error handling

from ibm_cloud_sdk_core import ApiException

try:
  # Invoke a Cloudant method request
except ApiException as ae:
  print("Method failed")
  print(" - status code: " + str(ae.code))
  print(" - error message: " + ae.message)
  if ("reason" in ae.http_response.json()):
    print(" - reason: " + ae.http_response.json()["reason"])

Other errors

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.

from requests import ConnectionError, ReadTimeout, RequestException, ValueError

try:
  # Invoke a Cloudant method request
except ConnectionError as cerr:
  print("Connection error occurred:")
  print(cerr)
except ReadTimeout as rt:
  # The server did not send any data in the allotted amount of time.
  print("Read timed out:")
  print(rt)
except RequestException as re:
  # Handle other request failures
  print("Request Exception:")
  print(re)
except ValueError as ve:
  print("Invalid argument value:\n" + ve.message)

Auditing

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.

Additional 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: $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"

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
Via
X-Content-Type-Options
X-CouchDB-Body-Time
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.

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-CouchDB-Body-Time

Time spent receiving the request body in milliseconds. Available when body content is included in the request.

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.

Pagination

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.

Paging on all documents and on views

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:

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

Paging with bookmarks

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 limiting

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

Numbers can be integer or floating point values.

Example of a number in JSON format

Strings

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"

Booleans

A true or false value.

Example of a boolean in JSON format

{
  "value": true
}

Arrays

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" } ]

Objects

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"
}

Logging

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.

// Enable Debug logging
core.SetLoggingLevel(core.LevelDebug)

HttpConfigOptions options =
    new HttpConfigOptions.Builder()
        .loggingLevel(HttpConfigOptions.LoggingLevel.BASIC)
    .build();

service.configureClient(options);

DEBUG=ibm-cloud-sdk-core:error    // enables error logs
DEBUG=ibm-cloud-sdk-core:warning  // enables warning logs and below
DEBUG=ibm-cloud-sdk-core:info     // enables info logs and below
DEBUG=ibm-cloud-sdk-core:verbose  // enables verbose logs and below
DEBUG=ibm-cloud-sdk-core:debug    // enables debug logs and below

import logging
logging.basicConfig(level=logging.DEBUG)

When you access the root of an instance, IBM Cloudant returns meta-information about the instance. The response includes a JSON structure that contains information about the server, including a welcome message and the server's version.

Tip: The authentication for this endpoint is only enforced when using IAM.