Introduction

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

GitHub

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

Installation

npm install --save @ibm-cloud/cloudant

GitHub

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

Installation

pip3 install ibmcloudant

GitHub

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

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:

  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.

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

Value
  • HTTP
  • 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.

Value
  • API Key
  • Cookie
  • 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.

Value
  • HTTP
  • JWT
  • 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").

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

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

123

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)

Methods

Retrieve server instance information

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.

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.

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.

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.

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.

GET /
(cloudant *CloudantV1) GetServerInformation(getServerInformationOptions *GetServerInformationOptions) (result *ServerInformation, response *core.DetailedResponse, err error)
(cloudant *CloudantV1) GetServerInformationWithContext(ctx context.Context, getServerInformationOptions *GetServerInformationOptions) (result *ServerInformation, response *core.DetailedResponse, err error)
ServiceCall<ServerInformation> getServerInformation()
getServerInformation(params)
get_server_information(
        self,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloudantnosqldb.account-meta-info.read

Request

No Request Parameters

This method does not accept any request parameters.

WithContext method only

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

  • curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X GET "$SERVICE_URL"
    
  • getServerInformationOptions := service.NewGetServerInformationOptions()
    
    serverInformation, response, err := service.GetServerInformation(getServerInformationOptions)
    if err != nil {
      panic(err)
    }
    
    b, _ := json.MarshalIndent(serverInformation, "", "  ")
    fmt.Println(string(b))
    
  • import com.ibm.cloud.cloudant.v1.Cloudant;
    import com.ibm.cloud.cloudant.v1.model.ServerInformation;
    
    Cloudant service = Cloudant.newInstance();
    
    ServerInformation response =
        service.getServerInformation().execute().getResult();
    
    System.out.println(response);
    
  • import { CloudantV1 } from '@ibm-cloud/cloudant';
    
    const service = CloudantV1.newInstance({});
    
    service.getServerInformation().then(response => {
        console.log(response.result);
    });
    
  • from ibmcloudant.cloudant_v1 import CloudantV1
    
    service = CloudantV1.new_instance()
    
    response = service.get_server_information().get_result()
    
    print(response)
    

Response

Schema for information about the server instance.

Schema for information about the server instance.

Schema for information about the server instance.

Schema for information about the server instance.

Schema for information about the server instance.

Status Code

  • HTTP response for / style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example ServerInformation response.

    {
      "couchdb": "Welcome",
      "features": [
        "access-ready",
        "iam",
        "partitioned",
        "pluggable-storage-engines",
        "scheduler"
      ],
      "features_flags": [
        "partitioned"
      ],
      "vendor": {
        "name": "IBM Cloudant",
        "variant": "paas",
        "version": 8162
      },
      "version": "2.1.1"
    }
  • Example ServerInformation response.

    {
      "couchdb": "Welcome",
      "features": [
        "access-ready",
        "iam",
        "partitioned",
        "pluggable-storage-engines",
        "scheduler"
      ],
      "features_flags": [
        "partitioned"
      ],
      "vendor": {
        "name": "IBM Cloudant",
        "variant": "paas",
        "version": 8162
      },
      "version": "2.1.1"
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Retrieve the HTTP headers for a server instance

Retrieves the HTTP headers for a server instance.

HEAD /

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloudantnosqldb.account-meta-info.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

  • Header returning the time spent receiving the request body. Available when body content included in the request.

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for / style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Retrieve cluster membership information

Displays the nodes that are part of the cluster as cluster_nodes. The field, all_nodes, displays all nodes this node knows about, including the ones that are part of the cluster. This endpoint is useful when you set up a cluster.

Displays the nodes that are part of the cluster as cluster_nodes. The field, all_nodes, displays all nodes this node knows about, including the ones that are part of the cluster. This endpoint is useful when you set up a cluster.

Displays the nodes that are part of the cluster as cluster_nodes. The field, all_nodes, displays all nodes this node knows about, including the ones that are part of the cluster. This endpoint is useful when you set up a cluster.

Displays the nodes that are part of the cluster as cluster_nodes. The field, all_nodes, displays all nodes this node knows about, including the ones that are part of the cluster. This endpoint is useful when you set up a cluster.

Displays the nodes that are part of the cluster as cluster_nodes. The field, all_nodes, displays all nodes this node knows about, including the ones that are part of the cluster. This endpoint is useful when you set up a cluster.

GET /_membership
(cloudant *CloudantV1) GetMembershipInformation(getMembershipInformationOptions *GetMembershipInformationOptions) (result *MembershipInformation, response *core.DetailedResponse, err error)
(cloudant *CloudantV1) GetMembershipInformationWithContext(ctx context.Context, getMembershipInformationOptions *GetMembershipInformationOptions) (result *MembershipInformation, response *core.DetailedResponse, err error)
ServiceCall<MembershipInformation> getMembershipInformation()
getMembershipInformation(params)
get_membership_information(
        self,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloudantnosqldb.cluster-membership.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-membership.read

Request

No Request Parameters

This method does not accept any request parameters.

WithContext method only

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

  • curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X GET "$SERVICE_URL/_membership"
    
  • getMembershipInformationOptions := service.NewGetMembershipInformationOptions()
    
    membershipInformation, response, err := service.GetMembershipInformation(getMembershipInformationOptions)
    if err != nil {
      panic(err)
    }
    
    b, _ := json.MarshalIndent(membershipInformation, "", "  ")
    fmt.Println(string(b))
    
  • import com.ibm.cloud.cloudant.v1.Cloudant;
    import com.ibm.cloud.cloudant.v1.model.MembershipInformation;
    
    Cloudant service = Cloudant.newInstance();
    
    MembershipInformation response =
        service.getMembershipInformation().execute().getResult();
    
    System.out.println(response);
    
  • import { CloudantV1 } from '@ibm-cloud/cloudant';
    
    const service = CloudantV1.newInstance({});
    
    service.getMembershipInformation().then(response => {
      console.log(response.result);
    });
    
  • from ibmcloudant.cloudant_v1 import CloudantV1
    
    service = CloudantV1.new_instance()
    
    response = service.get_membership_information().get_result()
    
    print(response)
    

Response

Schema for information about known nodes and cluster membership.

Schema for information about known nodes and cluster membership.

Schema for information about known nodes and cluster membership.

Schema for information about known nodes and cluster membership.

Schema for information about known nodes and cluster membership.

Status Code

  • HTTP response for /_membership style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example MembershipInformation response.

    {
      "all_nodes": [
        "node1@127.0.0.1",
        "node2@127.0.0.1",
        "node3@127.0.0.1"
      ],
      "cluster_nodes": [
        "node1@127.0.0.1",
        "node2@127.0.0.1",
        "node3@127.0.0.1"
      ]
    }
  • Example MembershipInformation response.

    {
      "all_nodes": [
        "node1@127.0.0.1",
        "node2@127.0.0.1",
        "node3@127.0.0.1"
      ],
      "cluster_nodes": [
        "node1@127.0.0.1",
        "node2@127.0.0.1",
        "node3@127.0.0.1"
      ]
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Retrieve the HTTP headers for cluster membership

Retrieves the HTTP headers for cluster membership.

HEAD /_membership

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloudantnosqldb.cluster-membership.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-membership.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

  • Header returning the time spent receiving the request body. Available when body content included in the request.

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_membership style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Retrieve information about cluster reshard operations

Retrieves a summary of the shard splitting operations for the whole cluster.

GET /_reshard

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Schema for the shard splitting cluster summary.

Status Code

  • HTTP response for /_reshard style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example ReshardInformation response.

    {
      "completed": 3,
      "failed": 4,
      "running": 0,
      "state": "stopped",
      "state_reason": "Manual rebalancing.",
      "stopped": 0,
      "total": 7
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Retrieve HTTP headers for cluster reshard operations

Retrieves the HTTP headers for cluster reshard operations.

HEAD /_reshard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloudantnosqldb.cluster-reshard-jobs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

  • Header returning the time spent receiving the request body. Available when body content included in the request.

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_reshard style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Retrieve a list of shard splitting jobs

List all shard splitting jobs.

GET /_reshard/jobs

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Schema for a list of shard splitting jobs.

Status Code

  • HTTP response for /_reshard/jobs style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example ReshardJobsInformation response.

    {
      "jobs": [
        {
          "history": [
            {
              "detail": null,
              "timestamp": "2019-02-06T22:28:06Z",
              "type": "new"
            },
            {
              "detail": null,
              "timestamp": "2019-02-06T22:28:10Z",
              "type": "completed"
            }
          ],
          "id": "001-0a308ef9f7bd24bd4887d6e619682a6d3bb3d0fd94625866c5216ec1167b4e23",
          "job_state": "completed",
          "node": "node1@127.0.0.1",
          "source": "shards/00000000-ffffffff/db1.1549492084",
          "split_state": "completed",
          "start_time": "2019-02-06T22:28:06Z",
          "state_info": {},
          "target": [
            "shards/00000000-7fffffff/db1.1549492084",
            "shards/80000000-ffffffff/db1.1549492084"
          ],
          "type": "split",
          "update_time": "2019-02-06T22:28:10Z"
        }
      ],
      "offset": 0,
      "total_rows": 1
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Retrieve HTTP headers of shard splitting jobs

Retrieves the HTTP headers for shard splitting jobs.

HEAD /_reshard/jobs

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloudantnosqldb.cluster-reshard-jobs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

  • Header returning the time spent receiving the request body. Available when body content included in the request.

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_reshard/jobs style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Create shard splitting jobs

Create shard splitting jobs.

POST /_reshard/jobs

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs.write

Request

HTTP request body for postReshardJobsConfiguration.

Examples:
ReshardJobsConfiguration

Response

Schema for the result of a shard splitting jobs response.

Status Code

  • HTTP response for postReshardJobsConfiguration.

  • HTTP response for postReshardJobsConfiguration.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for payload too large.

  • HTTP error for unsupported media type.

  • HTTP error for too many requests.

  • HTTP response for postReshardJobsConfiguration.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example postReshardJobsConfiguration response.

    [
      {
        "id": "001-30d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df557",
        "node": "node1@127.0.0.1",
        "ok": "true,",
        "shard": "shards/80000000-ffffffff/db3.1554148353"
      },
      {
        "id": "001-40d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df600",
        "node": "node2@127.0.0.1",
        "ok": "true,",
        "shard": "shards/80000000-ffffffff/db3.1554148353"
      }
    ]
  • Example postReshardJobsConfiguration response.

    [
      {
        "id": "001-30d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df557",
        "node": "node1@127.0.0.1",
        "ok": "true,",
        "shard": "shards/80000000-ffffffff/db3.1554148353"
      },
      {
        "id": "001-40d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df600",
        "node": "node2@127.0.0.1",
        "ok": "true,",
        "shard": "shards/80000000-ffffffff/db3.1554148353"
      }
    ]
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for a request with an attachment size that exceeds the allowable limit.

    {
      "error": "attachment_too_large",
      "reason": "attachment_name"
    }
  • Example error response for a request with a document size that exceeds the allowable limit.

    {
      "error": "document_too_large",
      "reason": "doc_id"
    }
  • Example error response for a request size that exceeds the limit.

    {
      "error": "too_large",
      "reason": "the request entity is too large"
    }
  • Example error response for unsupported media type.

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example postReshardJobsConfiguration response.

    [
      {
        "id": "001-30d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df557",
        "node": "node1@127.0.0.1",
        "ok": "true,",
        "shard": "shards/80000000-ffffffff/db3.1554148353"
      },
      {
        "id": "001-40d7848a6feeb826d5e3ea5bb7773d672af226fd34fd84a8fb1ca736285df600",
        "node": "node2@127.0.0.1",
        "ok": "true,",
        "shard": "shards/80000000-ffffffff/db3.1554148353"
      }
    ]
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Delete a shard splitting job

Stop and remove a shard splitting job.

DELETE /_reshard/jobs/{reshard_job_id}

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-job.delete

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Schema for an OK result.

Status Code

  • HTTP response for Ok operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example Ok response.

    {
      "ok": true
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Retrieve information about a shard splitting job

Retrieves the state of a shard splitting job.

GET /_reshard/jobs/{reshard_job_id}

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-job.read

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Schema for the state of a shard splitting job.

Status Code

  • HTTP response for /_reshard/jobs/{reshard_job_id} style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example ReshardJobInformation response.

    {
      "history": [
        {
          "detail": {
            "timestamp": "2019-02-06T22:28:06Z",
            "type": "new"
          }
        },
        {
          "detail": {
            "timestamp": "2019-02-06T22:28:10Z",
            "type": "completed"
          }
        }
      ],
      "id": "001-0a308ef9f7bd24bd4887d6e619682a6d3bb3d0fd94625866c5216ec1167b4e23",
      "job_state": "completed",
      "node": "node1@127.0.0.1",
      "source": "shards/00000000-ffffffff/db1.1549492084",
      "split_state": "completed",
      "start_time": "2019-02-06T22:28:06Z",
      "target": [
        "shards/00000000-7fffffff/db1.1549492084",
        "shards/80000000-ffffffff/db1.1549492084"
      ],
      "type": "split",
      "update_time": "2019-02-06T22:28:10Z"
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Retrieve information about a shard splitting job

Retrieves the state of a shard splitting job.

HEAD /_reshard/jobs/{reshard_job_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloudantnosqldb.cluster-reshard-job.read

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Response Headers

  • Header returning an identifier for the request.

  • Header returning the time spent receiving the request body. Available when body content included in the request.

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_reshard/jobs/{reshard_job_id} style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Retrieve the running state of a shard splitting job

Retrieves the running state of a shard splitting job.

GET /_reshard/jobs/{reshard_job_id}/state

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs-state.read

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Schema for the state information of a shard splitting job.

Status Code

  • HTTP response for /_reshard/state style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example request or response body for the state of cluster resharding.

    {
      "reason": "Pause resharding across the cluster.",
      "state": "stopped"
    }
  • Example request or response body for the state of a reshard job.

    {
      "reason": "Pause this job for now.",
      "state": "stopped"
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Retrieve HTTP headers of a shard splitting job

Retrieves the HTTP headers of a shard splitting job.

HEAD /_reshard/jobs/{reshard_job_id}/state

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • cloudantnosqldb.cluster-reshard-jobs-state.read

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Response Headers

  • Header returning an identifier for the request.

  • Header returning the time spent receiving the request body. Available when body content included in the request.

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_reshard/state style operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Update the running state of a shard splitting job

Update the running state of a shard splitting job. The state can be changed from stopped to running or from running to stopped. If an individual job is stopped via this API it will stay stopped even after the global resharding state is toggled from stopped to running. If the job is already completed its state will stay completed.

PUT /_reshard/jobs/{reshard_job_id}/state

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs-state.write

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

HTTP request body for putReshardState or putReshardJobState.

Examples:
ReshardStateCluster
ReshardStateJob

Response

Schema for an OK result.

Status Code

  • HTTP response for Ok operations.

  • HTTP error for bad request.

  • HTTP error for unauthorized.

  • HTTP error for payment required.

  • HTTP error for forbidden.

  • HTTP error for not found.

  • HTTP error for timeout reading client request.

  • HTTP error for gone.

  • HTTP error for payload too large.

  • HTTP error for unsupported media type.

  • HTTP error for too many requests.

  • HTTP error for internal server error.

  • HTTP error for bad gateway.

  • HTTP error for service unavailable.

  • HTTP error for gateway timeout.

Example responses
  • Example Ok response.

    {
      "ok": true
    }
  • Example error response for an invalid base64 header value.

    {
      "error": "bad_request",
      "reason": "Authorization header has invalid base64 value"
    }
  • Example error response for a bad request.

    {
      "error": "bad_request",
      "reason": "Bad request."
    }
  • Example error response for a bad request for too many UUIDs.

    {
      "error": "bad_request",
      "reason": "count parameter too large"
    }
  • Example error response for a bad request deleting a database with a document rev.

    {
      "error": "bad_request",
      "reason": "You tried to DELETE a database with a ?=rev parameter. Did you mean to DELETE a document instead?"
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for an invalid database name.

    {
      "error": "illegal_database_name",
      "reason": "Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter."
    }
  • Example error response for a bad request with invalid UTF-8 JSON.

    {
      "error": "bad_request",
      "reason": "invalid UTF-8 JSON"
    }
  • Example error response for a bad request with an invalid partition name.

    {
      "error": "bad_request",
      "reason": "invalid_partition_req"
    }
  • Example error response for a bad request with an unsupported option.

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • Example error response for incorrect credentials.

    {
      "error": "unauthorized",
      "reason": "Name or password is incorrect."
    }
  • Example error response for reader access is required for this request.

    {
      "error": "unauthorized",
      "reason": "_reader access is required for this request."
    }
  • Example error response for writer or creator access is required.

    {
      "error": "unauthorized",
      "reason": "one of _writer, _creator is required for this request."
    }
  • Example error response for writer access is required.

    {
      "error": "unauthorized",
      "reason": "_writer access is required for this request."
    }
  • Example error response when payment is required. For example, if the data quota of the plan is exceeded.

    {
      "error": "payment_required",
      "reason": "Payment required"
    }
  • Example error response for a forbidden request.

    {
      "error": "forbidden",
      "reason": "server_admin access is required for this request"
    }
  • Example error response for a database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • Example error response for a missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • Example error response for timeout reading client request.

    {
      "error": "request_timeout",
      "reason": "Request timeout"
    }
  • Example error response for gone.

    {
      "error": "gone",
      "reason": "The requested resource is no longer located here, verify your DNS\nsettings.\n"
    }
  • Example error response for a request with an attachment size that exceeds the allowable limit.

    {
      "error": "attachment_too_large",
      "reason": "attachment_name"
    }
  • Example error response for a request with a document size that exceeds the allowable limit.

    {
      "error": "document_too_large",
      "reason": "doc_id"
    }
  • Example error response for a request size that exceeds the limit.

    {
      "error": "too_large",
      "reason": "the request entity is too large"
    }
  • Example error response for unsupported media type.

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • Example error response for too many requests.

    {
      "error": "too_many_requests",
      "reason": "You`ve exceeded your rate limit allowance. Please try again later.\n"
    }
  • Example error response for an unknown server error.

    {
      "error": "unknown_error",
      "reason": "function_clause",
      "ref": 2632214382
    }
  • Example error response for bad gateway.

    {
      "error": "bad_gateway",
      "reason": "Bad gateway"
    }
  • Example error response for service unavailable.

    {
      "error": "service_unavailable",
      "reason": "Service unavailable"
    }
  • Example error response for gateway timeout.

    {
      "error": "gateway_timeout",
      "reason": "Gateway timeout"
    }

Retrieve the state of shard splitting across the cluster

Retrieves the state of shard splitting across the cluster.

GET /_reshard/state

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs-state.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Schema for the state information of a shard splitting job.