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:
- Go to the IBM Cloud dashboard and open an instance.
- Click the Service credentials tab.
- Click the chevron next to the service credentials to open the credentials pane.
- Copy the value from the
host
field and prefix it with thehttps://
protocol. This value is the external endpoint.
For more information, see the Locating your service credentials tutorial.
Or you can copy your external endpoint by following these steps:
- Go to the IBM Cloud dashboard and open an instance.
- Under the Manage tab on the Overview page, see the External endpoint in the table.
- Click Copy to copy the External endpoint. Paste the endpoint where you need your credentials.
A public endpoint looks something like these examples:
https://5lll032-dd12-536e-09b3-432fg9f07e78-bluemix.cloudantnosqldb.appdomain.cloud
or
https://5lll032-dd12-536e-09b3-432fg9f07e78-bluemix.cloudant.com
A private endpoint is one that is only accessible through a non-public network, like IBM's internal network. Private endpoints are available to customers who have the Dedicated Hardware plan.
Authentication
You can access IBM Cloudant with IBM Cloud® Identity and Access Management (IAM) or IBM Cloudant legacy access controls. The choice between Use only IAM and Use both legacy credentials and IAM access control affects how credentials are delivered to your application when you bind and generate service credentials.
The Use only IAM option is preferred. Review Must I use Use only IAM or Use both legacy credentials and IAM? to help with making a decision.
IAM authentication
Access to IBM Cloudant is centrally controlled by IBM Cloud® Identity and Access Management (IAM), which provides a unified approach to managing user identities, and access control across your IBM Cloud® services and applications using the same set of credentials.
To work with the API, authenticate your application or service by including your IBM Cloud® IAM access token in API requests.
Cloudant legacy authentication
Legacy access controls are unique to IBM Cloudant, which means that accessing each service instance requires its own set of credentials. These credentials can be used with HTTP basic and cookie authentication. IBM Cloudant legacy API keys authenticate identically to username and password credentials but are generated and assigned differently. For more information, see the documentation about IBM Cloudant legacy API keys.
Additional authentication resources
- IBM Cloudant client libraries provide full integration with IAM's access controls and automatically retrieve an IAM access token when an appropriate IAM configuration is provided (for example, an IAM API key or IAM profile ID).
- View IBM Cloudant authentication documentation.
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.
- 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.
- 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
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.
Paging on all documents and on views
The following endpoints have the limit
and skip
parameters which allow you to define how many documents you would
like to see on a page, and the offset into the range you want to start the page from, but this pattern gets
progressively slower the larger the value of skip
gets.
There are a couple of options which are more efficient than using the limit
/skip
pattern:
either fetch one extra document, and use this document's id
as the startKey
of your request for the next page of results ("fetch one document too many"); or append \u0000
to the startKey
, using the last id
of the last document from your previous page of results ("the \u0000
trick").
The following endpoints have the Limit
and Skip
parameters which allow you to define how many documents you would
like to see on a page, and the offset into the range you want to start the page from, but this pattern gets
progressively slower the larger the value of Skip
gets.
There are a couple of options which are more efficient than using the Limit
/Skip
pattern:
either fetch one extra document, and use this document's ID
as the StartKey
of your request for the next page of results ("fetch one document too many"); or append \u0000
to the StartKey
, using the last ID
of the last document from your previous page of results ("the \u0000
trick").
- GET /{db}/_all_docs
- POST /{db}/_all_docs
- GET /{db}/_partition/{partition_key}/_all_docs
- POST /{db}/_partition/{partition_key}/_all_docs
- GET /{db}/_design/{ddoc}/_view/{view}
- POST /{db}/_design/{ddoc}/_view/{view}
- GET /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}
- POST /{db}/_partition/{partition_key}/_design/{ddoc}/_view/{view}
You can find examples and more explanation for both tricks in the Cloudant docs:
We recommend to use "the \u0000 trick" over "fetch one document too many".
Paging with bookmarks
The following endpoints use bookmarks as the key to access the next page of results from the result set. If you want to learn about the usage of bookmarks we recommend reading how IBM Cloudant bookmarks work.
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.
Related APIs
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.
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
Request
No Request Parameters
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
No Request Parameters
No Request Parameters
No Request Parameters
No 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.
Welcome message.
List of enabled optional features.
Schema for server vendor information.
Apache CouchDB version.
List of feature flags.
Schema for information about the server instance.
Welcome message.
List of enabled optional features.
Schema for server vendor information.
Vendor name.
Vendor variant.
Vendor version.
Vendor
Apache CouchDB version.
List of feature flags.
Schema for information about the server instance.
Welcome message.
List of enabled optional features.
Schema for server vendor information.
Vendor name.
Vendor variant.
Vendor version.
vendor
Apache CouchDB version.
List of feature flags.
Schema for information about the server instance.
Welcome message.
List of enabled optional features.
Schema for server vendor information.
Vendor name.
Vendor variant.
Vendor version.
vendor
Apache CouchDB version.
List of feature flags.
Schema for information about the server instance.
Welcome message.
List of enabled optional features.
Schema for server vendor information.
Vendor name.
Vendor variant.
Vendor version.
vendor
Apache CouchDB version.
List of feature flags.
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 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 /
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
Request
No Request Parameters
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
No Request Parameters
No Request Parameters
No Request Parameters
No 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.
List of nodes this node knows about, including the ones that are part of the cluster.
All cluster nodes.
Schema for information about known nodes and cluster membership.
List of nodes this node knows about, including the ones that are part of the cluster.
All cluster nodes.
Schema for information about known nodes and cluster membership.
List of nodes this node knows about, including the ones that are part of the cluster.
All cluster nodes.
Schema for information about known nodes and cluster membership.
List of nodes this node knows about, including the ones that are part of the cluster.
All cluster nodes.
Schema for information about known nodes and cluster membership.
List of nodes this node knows about, including the ones that are part of the cluster.
All cluster nodes.
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 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
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
Response
Schema for the shard splitting cluster summary.
Number of complete jobs.
Possible values: value ≥ 0
Number of failed jobs.
Possible values: value ≥ 0
Number of running jobs.
Possible values: value ≥ 0
States of the shard splitting application. When shard splitting is running on the cluster then all the jobs that haven't been individually stopped will be running as well. When shard splitting is stopped then all the shard splitting jobs will be stopped on the cluster.
Possible values: [
running
,stopped
]State reason.
Number of stopped jobs.
Possible values: value ≥ 0
Total number of jobs.
Possible values: value ≥ 0
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 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
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.
Response
Schema for a list of shard splitting jobs.
Offset where the list started.
Possible values: 0 ≤ value ≤ 4294967295
Number of total rows.
Possible values: 0 ≤ value ≤ 4294967295
All split 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 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
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.
Request
HTTP request body for postReshardJobsConfiguration.
Job type. Currently the only type accepted is split.
Allowable values: [
split
]Schema for a database name.
Possible values: length ≤ 238, Value must match regular expression
^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$| ^[a-z][a-z0-9_$()+/-]*$
Node name.
Shard range.
Database shard.
Response
Schema for the result of a shard splitting jobs response.
Node name.
Database shard.
ok
The cause of the error (if available).
The name of the error.
The reason the error occurred (if available).
Schema for a document ID.
Possible values: Value must match regular expression
^([^_]|_(design|local)/).+
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 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}
Response
Schema for an OK result.
ok
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 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}
Response
Schema for the state of a shard splitting job.
The timeline of job state transitions with a timestamp and additional details (if available).
The ID of the job.
This is the running state of the job.
Possible values: [
completed
,failed
,new
,running
,stopped
]Node where this job is running.
Source shard.
How far along the shard splitting process has progressed.
Possible values: [
build_indices
,completed
,copy_local_docs
,initial_copy
,new
,source_delete
,topoff1
,topoff2
,topoff3
,update_shard_map
,wait_source_close
]Time when job had started running last. A job might have been stopped or the node restarted to this time might not match with the creation time.
Additional information about the current running state. On retry it will include the last error that cause the retry to happen.
Failure reason.
state_info
Target shards.
Job type. Currently the only type accepted is split.
Possible values: [
split
]Time of the last update to the job state.
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 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}
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
Response
Schema for the state information of a shard splitting job.
Reason for job state.
Job state.
Possible values: [
completed
,failed
,running
,stopped
]
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 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
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
Request
Path Parameters
Path parameter to specify the shard splitting job ID.
HTTP request body for putReshardState or putReshardJobState.
Reason for job state.
Job state.
Allowable values: [
completed
,failed
,running
,stopped
]
Response
Schema for an OK result.
ok
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 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" }