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.

The code examples on this tab use the IBM Cloudant SDK for Java&trade.

Gradle

compile group: 'com.ibm.cloud', name: 'cloudant', version: '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

GitHub

Authentication

Access to IBM Cloudant is 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.

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

For further information on authentication:

Security scheme

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

Basic

Value
  • HTTP
  • Basic

Cookie

Value
  • API Key
  • Cookie
  • AuthSession

IAM

Value
  • API Key
  • Header
  • Authorization

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 creds file avoids hardcoding 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>.

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

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=<varname>apikey</varname>
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("<varname>apikey</varname>");

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: '<varname>apikey</varname>'
});

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('<varname>apikey</varname>')

service = CloudantV1(authenticator=authenticator)

service.set_service_url('{url}')
import (
    "github.com/ibm/cloudant-go-sdk"
    "github.com/IBM/go-sdk-core/core"
)

authenticator := &core.IamAuthenticator{
    ApiKey: "<varname>apikey</varname>",
}

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.cloudant.security.CouchDbSessionAuthenticator;

CouchDbSessionAuthenticator authenticator = (CouchDbSessionAuthenticator)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"
    "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("{username}", "{password}");

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 ibmcloudant import CouchDbSessionAuthenticator
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"
    "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)
}

Event tracking

You can monitor API activity within your account by using the IBM Cloud® Activity Tracker service. An event is generated whenever an API method is called, and you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

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

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.
409 - Conflict Request resulted in an update conflict.
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.
417 - Expectation Failed Returned if the unsupported all_or_nothing option is used when the client tries to send documents in bulk.
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.
503 - Service Unavailable The request could not be processed. Seeing this response might indicate a misspelled IBM Cloudant account name.

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;

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());
}

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

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.

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

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

from requests import ConnectionError, ReadTimeout, RequestException

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)

Logging

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.

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.

GET /

Authorization

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

  • cloudantnosqldb.account-meta-info.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.account-meta-info.read

Request

No Request Parameters

This method does not accept any request parameters.

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

Response

Schema for information about the server instance.

Status Code

  • HTTP response for / style operations.

  • HTTP response for errors.

Example responses
  • Example ServerInformation response.

    {
      "couchdb": "Welcome",
      "features": [
        "access-ready",
        "geo",
        "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 administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve the HTTP headers for a server instance

Retrieves the HTTP headers for a server instance.

HEAD /

Authorization

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

  • cloudantnosqldb.account-meta-info.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.account-meta-info.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

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

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for / style operations.

  • HTTP response for errors.

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.

GET /_membership

Authorization

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

  • cloudantnosqldb.cluster-membership.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-membership.read

Request

No Request Parameters

This method does not accept any request parameters.

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

Status Code

  • HTTP response for /_membership style operations.

  • HTTP response for errors.

Example responses
  • Example MembershipInformation response.

    {
      "all_nodes": [
        "node1@127.0.0.1",
        "node2@127.0.0.1",
        "node3@127.0.0.1"
      ],
      "cluster_nodes": [
        "node1@127.0.0.1",
        "node2@127.0.0.1",
        "node3@127.0.0.1"
      ]
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve the HTTP headers for cluster membership

Retrieves the HTTP headers for cluster membership.

HEAD /_membership

Authorization

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

  • cloudantnosqldb.cluster-membership.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-membership.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

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

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_membership style operations.

  • HTTP response for errors.

Retrieve information about cluster reshard operations

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

GET /_reshard

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Schema for the shard splitting cluster summary.

Status Code

  • HTTP response for /_reshard style operations.

  • HTTP response for errors.

Example responses
  • Example ReshardInformation response.

    {
      "completed": 3,
      "failed": 4,
      "running": 0,
      "state": "stopped",
      "state_reason": "Manual rebalancing.",
      "stopped": 0,
      "total": 7
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve HTTP headers for cluster reshard operations

Retrieves the HTTP headers for cluster reshard operations.

HEAD /_reshard

Authorization

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

  • cloudantnosqldb.cluster-reshard-jobs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

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

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_reshard style operations.

  • HTTP response for errors.

Retrieve a list of shard splitting jobs

List all shard splitting jobs.

GET /_reshard/jobs

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Schema for a list of shard splitting jobs.

Status Code

  • HTTP response for /_reshard/jobs style operations.

  • HTTP response for errors.

Example responses
  • Example ReshardJobsInformation response.

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

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve HTTP headers of shard splitting jobs

Retrieves the HTTP headers for shard splitting jobs.

HEAD /_reshard/jobs

Authorization

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

  • cloudantnosqldb.cluster-reshard-jobs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

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

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_reshard/jobs style operations.

  • HTTP response for errors.

Create shard splitting jobs

Create shard splitting jobs.

POST /_reshard/jobs

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-jobs.write

Request

HTTP request body for postReshardJobsConfiguration.

Examples:
ReshardJobsConfiguration

Response

Schema for the result of a shard splitting jobs response.

Status Code

  • HTTP response for postReshardJobsConfiguration.

  • HTTP response for errors.

  • HTTP response for postReshardJobsConfiguration.

  • HTTP response for errors.

Example responses
  • Example postReshardJobsConfiguration response.

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

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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 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 administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Delete a shard splitting job

Stop and remove a shard splitting job.

DELETE /_reshard/jobs/{reshard_job_id}

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-job.delete

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Schema for an OK result.

Status Code

  • HTTP response for Ok operations.

  • HTTP response for errors.

Example responses
  • Example Ok response.

    {
      "ok": true
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve information about a shard splitting job

Retrieves the state of a shard splitting job.

GET /_reshard/jobs/{reshard_job_id}

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-reshard-job.read

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Schema for the state of a shard splitting job.

Status Code

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

  • HTTP response for errors.

Example responses
  • Example ReshardJobInformation response.

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

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve information about a shard splitting job

Retrieves the state of a shard splitting job.

HEAD /_reshard/jobs/{reshard_job_id}

Authorization

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

  • cloudantnosqldb.cluster-reshard-job.read

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Response Headers

  • Header returning an identifier for the request.

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

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

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

  • HTTP response for errors.

Retrieve the running state of a shard splitting job

Retrieves the running state of a shard splitting job.

GET /_reshard/jobs/{reshard_job_id}/state

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Schema for the state information of a shard splitting job.

Status Code

  • HTTP response for /_reshard/state style operations.

  • HTTP response for errors.

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

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

    {
      "reason": "Pause this job for now.",
      "state": "stopped"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve HTTP headers of a shard splitting job

Retrieves the HTTP headers of a shard splitting job.

HEAD /_reshard/jobs/{reshard_job_id}/state

Authorization

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

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

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

Response

Response Headers

  • Header returning an identifier for the request.

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

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_reshard/state style operations.

  • HTTP response for errors.

Update the running state of a shard splitting job

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

PUT /_reshard/jobs/{reshard_job_id}/state

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • Path parameter to specify the shard splitting job ID.

HTTP request body for putReshardState or putReshardJobState.

Examples:
ReshardStateCluster
ReshardStateJob

Response

Schema for an OK result.

Status Code

  • HTTP response for Ok operations.

  • HTTP response for errors.

Example responses
  • Example Ok response.

    {
      "ok": true
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve the state of shard splitting across the cluster

Retrieves the state of shard splitting across the cluster.

GET /_reshard/state

Auditing

Calling this method generates the following auditing event.

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

Request

No Request Parameters

This method does not accept any request parameters.

Response

Schema for the state information of a shard splitting job.

Status Code

  • HTTP response for /_reshard/state style operations.

  • HTTP response for errors.

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

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

    {
      "reason": "Pause this job for now.",
      "state": "stopped"
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve HTTP headers of shard splitting across the cluster

Retrieves the HTTP headers of shard splitting across the cluster.

HEAD /_reshard/state

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

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

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_reshard/state style operations.

  • HTTP response for errors.

Enable/disable shard splitting across the cluster

Enable/disable shard splitting across the cluster. The states are stopped or running. This starts and stops global resharding on all the nodes of the cluster. If there are any running jobs, they will be stopped when the state changes to stopped. When the state changes back to running those job will continue running.

PUT /_reshard/state

Auditing

Calling this method generates the following auditing event.

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

Request

HTTP request body for putReshardState or putReshardJobState.

Examples:
ReshardStateCluster
ReshardStateJob

Response

Schema for an OK result.

Status Code

  • HTTP response for Ok operations.

  • HTTP response for errors.

Example responses
  • Example Ok response.

    {
      "ok": true
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve one or more UUIDs

Requests one or more Universally Unique Identifiers (UUIDs) from the instance. The response is a JSON object that provides a list of UUIDs.

GET /_uuids

Authorization

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

  • cloudantnosqldb.cluster-uuids.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-uuids.read

Request

Query Parameters

  • Query parameter to specify the number of UUIDs to return.

    Possible values: 1 ≤ value ≤ 1000

    Default: 1

  • curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X GET "$SERVICE_URL/_uuids?count=10"
  • getUuidsOptions := service.NewGetUuidsOptions()
    getUuidsOptions.SetCount(10)
    
    uuidsResult, response, err := service.GetUuids(getUuidsOptions)
    if err != nil {
      panic(err)
    }
    
    b, _ := json.MarshalIndent(uuidsResult, "", "  ")
    fmt.Println(string(b))
    
  • import com.ibm.cloud.cloudant.v1.Cloudant;
    import com.ibm.cloud.cloudant.v1.model.UuidsResult;
    
    Cloudant service = Cloudant.newInstance();
    
    GetUuidsOptions uuidsOptions = new GetUuidsOptions.Builder()
        .count(10)
        .build();
    
    UuidsResult response =
        service.getUuids(uuidsOptions).execute()
            .getResult();
    
    System.out.println(response);
    
  • import { CloudantV1 } from '@ibm-cloud/cloudant';
    
    const service = CloudantV1.newInstance({});
    
    const uuidsParams: CloudantV1.GetUuidsParams = {
      count: 10
    };
    
    service.getUuids(uuidsParams).then(response => {
      console.log(response.result);
    });
    
  • from ibmcloudant.cloudant_v1 import CloudantV1
    
    service = CloudantV1.new_instance()
    
    response = service.get_uuids(count=10).get_result()
    
    print(response)
    

Response

Schema for a set of uuids generated by the server.

Status Code

  • HTTP response for /_uuids style operations.

  • HTTP response for errors.

Example responses
  • Example UuidsResult response.

    {
      "uuids": [
        "75480ca477454894678e22eec6002413",
        "75480ca477454894678e22eec600250b",
        "75480ca477454894678e22eec6002c41",
        "75480ca477454894678e22eec6003b90",
        "75480ca477454894678e22eec6003fca",
        "75480ca477454894678e22eec6004bef",
        "75480ca477454894678e22eec600528f",
        "75480ca477454894678e22eec6005e0b",
        "75480ca477454894678e22eec6006158",
        "75480ca477454894678e22eec6006161"
      ]
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve HTTP headers for one or more UUIDs

Retrieves the HTTP headers for one or more UUIDs.

HEAD /_uuids

Authorization

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

  • cloudantnosqldb.cluster-uuids.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.cluster-uuids.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning an identifier for the request.

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

  • Header returning the Cloudant IAM action of the request.

  • Header returning the Cloudant backend that handled the request.

  • Header returning the Cloudant class of the request.

Status Code

  • HTTP response for /_uuids style operations.

  • HTTP response for errors.

Retrieve provisioned throughput capacity information

View the amount of provisioned throughput capacity that is allocated to an IBM Cloudant instance and what is the target provisioned throughput capacity.

GET /_api/v2/user/capacity/throughput

Authorization

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

  • cloudantnosqldb.account-capacity-throughput.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.account-capacity-throughput.read

Request

No Request Parameters

This method does not accept any request parameters.

  • ibmcloud cloudant c capacity

Response

Schema for information about the currently provisioned and target throughput capacity.

Status Code

  • HTTP response for getCapacityThroughputInformation.

  • HTTP response for errors.

Example responses
  • Example CapacityThroughputInformation response.

    {
      "current": {
        "throughput": {
          "blocks": 5,
          "query": 25,
          "read": 500,
          "write": 250
        }
      },
      "target": {
        "throughput": {
          "blocks": 10,
          "query": 50,
          "read": 1000,
          "write": 500
        }
      }
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Update the target provisioned throughput capacity

Sets the target provisioned throughput capacity for an IBM Cloudant instance. When target capacity is changed, the current capacity asynchronously changes to meet the target capacity.

PUT /_api/v2/user/capacity/throughput

Authorization

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

  • cloudantnosqldb.account-capacity-throughput.configure

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.account-capacity-throughput.configure

Request

HTTP request body for putCapacityThroughputConfiguration.

Examples:
CapacityThroughputConfiguration
  • ibmcloud cloudant c capacity-update --blocks 10

Response

Schema for information about the currently provisioned and target throughput capacity.

Status Code

  • HTTP response for getCapacityThroughputInformation.

  • HTTP response for errors.

Example responses
  • Example CapacityThroughputInformation response.

    {
      "current": {
        "throughput": {
          "blocks": 5,
          "query": 25,
          "read": 500,
          "write": 250
        }
      },
      "target": {
        "throughput": {
          "blocks": 10,
          "query": 50,
          "read": 1000,
          "write": 500
        }
      }
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Query a list of all database names in the instance

GET /_all_dbs

Authorization

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

  • cloudantnosqldb.account-all-dbs.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.account-all-dbs.read

Request

Query Parameters

  • Query parameter to specify whether to return the documents in descending by key order.

    Default: false

  • Query parameter to specify to stop returning records when the specified key is reached. String representation of any JSON type that matches the key type emitted by the view function.

  • Query parameter to specify the number of returned documents to limit the result to.

    Possible values: value ≥ 0

  • Query parameter to specify the number of records before starting to return the results.

    Possible values: value ≥ 0

  • Query parameter to specify to start returning records from the specified key. String representation of any JSON type that matches the key type emitted by the view function.

  • curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X GET "$SERVICE_URL/_all_dbs"
  • getAllDbsOptions := service.NewGetAllDbsOptions()
    
    result, response, err := service.GetAllDbs(getAllDbsOptions)
    if err != nil {
      panic(err)
    }
    
    b, _ := json.MarshalIndent(result, "", "  ")
    fmt.Println(string(b))
    
  • import com.ibm.cloud.cloudant.v1.Cloudant;
    import com.ibm.cloud.cloudant.v1.model.GetAllDbsOptions;
    import java.util.List;
    
    Cloudant service = Cloudant.newInstance();
    
    List<String> response =
        service.getAllDbs().execute().getResult();
    
    System.out.println(response);
    
  • import { CloudantV1 } from '@ibm-cloud/cloudant';
    
    const service = CloudantV1.newInstance({});
    
    service.getAllDbs().then(response => {
      console.log(response.result);
    });
    
  • from ibmcloudant.cloudant_v1 import CloudantV1
    
    service = CloudantV1.new_instance()
    
    response = service.get_all_dbs().get_result()
    
    print(response)
    

Response

Schema for a list of database names.

Status Code

  • HTTP response for /_all_dbs style operations.

  • HTTP response for errors.

Example responses
  • Example AllDbs response.

    [
      "events",
      "orders",
      "products",
      "stores",
      "users"
    ]
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Retrieve the HTTP headers for all database names in the instance

HEAD /_all_dbs

Authorization

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

  • cloudantnosqldb.account-all-dbs.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.account-all-dbs.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Headers

  • Header returning the double quoted base64 encoded MD5 binary digest.

  • 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 /_all_dbs style operations.

  • HTTP response for errors.

Query information about multiple databases

This operation enables you to request information about multiple databases in a single request, instead of issuing multiple GET /{db} requests. It returns a list that contains an information object for each database specified in the request.

POST /_dbs_info

Authorization

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

  • cloudantnosqldb.account-dbs-info.read

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.account-dbs-info.read

Request

HTTP request body for postDbsInfo.

Examples:
DbsInfoQuery
  • curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X POST "$SERVICE_URL/_dbs_info" -H "Content-Type: application/json" --data '{
      "keys":  ["products", "users", "orders"]
    }'
  • postDbsInfoOptions := service.NewPostDbsInfoOptions([]string{
      "products",
      "users",
      "orders",
    })
    
    dbsInfoResult, response, err := service.PostDbsInfo(postDbsInfoOptions)
    if err != nil {
      panic(err)
    }
    
    b, _ := json.MarshalIndent(dbsInfoResult, "", "  ")
    fmt.Println(string(b))
    
  • import com.ibm.cloud.cloudant.v1.Cloudant;
    import com.ibm.cloud.cloudant.v1.model.DbsInfoResult;
    import com.ibm.cloud.cloudant.v1.model.PostDbsInfoOptions;
    import java.util.Arrays;
    import java.util.List;
    
    Cloudant service = Cloudant.newInstance();
    
    PostDbsInfoOptions dbsInfoOptions =
        new PostDbsInfoOptions.Builder()
            .keys(Arrays.asList("products", "users", "orders"))
            .build();
    
    List<DbsInfoResult> response =
        service.postDbsInfo(dbsInfoOptions).execute()
            .getResult();
    
    System.out.println(response);
    
  • import { CloudantV1 } from '@ibm-cloud/cloudant';
    
    const service = CloudantV1.newInstance({});
    
    service.postDbsInfo({
      keys: ['products', 'users', 'orders']
    }).then(response => {
      console.log(response.result);
    });
    
  • from ibmcloudant.cloudant_v1 import CloudantV1
    
    service = CloudantV1.new_instance()
    
    response = service.post_dbs_info(
      keys=['products', 'users', 'orders']
    ).get_result()
    
    print(response)
    

Response

Schema for a list of database information objects.

Status Code

  • HTTP response for postDbsInfo.

  • HTTP response for errors.

Example responses
  • Example DbsInfoResults response.

    [
      {
        "info": {
          "cluster": {
            "n": 8,
            "q": 1,
            "r": 1,
            "w": 1
          },
          "compact_running": false,
          "db_name": "products",
          "disk_format_version": 8,
          "doc_count": 5,
          "doc_del_count": 1,
          "instance_start_time": "0",
          "partitioned_indexes": {
            "count": 4,
            "indexes": {
              "search": 2,
              "view": 2
            },
            "limit": 10
          },
          "props": {
            "partitioned": true
          },
          "purge_seq": 0,
          "sizes": {
            "active": 8887,
            "external": 1872,
            "file": 685680
          },
          "update_seq": "89-g1AAAALReJyd0T8OgjAUBvCKjq6ewM2BQPyz6hUUeoAWSExDIDE4ewqvoNBLeAouwRmE58diQprY4PR16C9f-17KGJufpzFbxjLKL8khljs3SvNrLLLC8_zv2c2SIsVlRzC54DxUwhmyzW_WIy5XWldKTEYV9kjLPVFnSFsnEEn0Bob0LRIolErrUgk2lGuLBKrkjag1pK0TqMtm7MT53XivpRUsAEM8MSxjN5YJg5VgiDfRa-xmwVowxJHz-o9ufLhGPLRujJltrRofbhDYNGFq6gOYofZj"
        },
        "key": "products"
      },
      {
        "info": {
          "cluster": {
            "n": 3,
            "q": 8,
            "r": 2,
            "w": 2
          },
          "compact_running": false,
          "db_name": "users",
          "disk_format_version": 8,
          "doc_count": 11,
          "doc_del_count": 0,
          "instance_start_time": "0",
          "purge_seq": "8-g1AAAALReJyd0T8OgjAUBvCKjq6ewM2BQPyz6hUUeoAWSExDIDE4ewqvoNBLeAouwRmE58diQprY4PR16C9f-17KGJufpzFbxjLKL8khljs3SvNrLLLC8_zv2c2SIsVlRzC54DxUwhmyzW_WIy5XWldKTEYV9kjLPVFnSFsnEEn0Bob0LRIolErrUgk2lGuLBKrkjag1pK0TqMtm7MT53XivpRUsAEM8MSxjN5YJg5VgiDfRa-xmwVowxJHz-o9ufLhGPLRujJltrRofbhDYNGFq6gOYofZj",
          "sizes": {
            "active": 67475,
            "external": 2339,
            "file": 3872387
          },
          "update_seq": "13-g1AAAALReJyd0T8OgjAUBvCKjq6ewM2BQPyz6hUUeoAWSExDIDE4ewqvoNBLeAouwRmE58diQprY4PR16C9f-17KGJufpzFbxjLKL8khljs3SvNrLLLC8_zv2c2SIsVlRzC54DxUwhmyzW_WIy5XWldKTEYV9kjLPVFnSFsnEEn0Bob0LRIolErrUgk2lGuLBKrkjag1pK0TqMtm7MT53XivpRUsAEM8MSxjN5YJg5VgiDfRa-xmwVowxJHz-o9ufLhGPLRujJltrRofbhDYNGFq6gOYofZj"
        },
        "key": "users"
      },
      {
        "info": {
          "cluster": {
            "n": 3,
            "q": 8,
            "r": 2,
            "w": 2
          },
          "compact_running": false,
          "db_name": "orders",
          "disk_format_version": 8,
          "doc_count": 5,
          "doc_del_count": 0,
          "instance_start_time": "0",
          "purge_seq": "8-g1AAAALReJyd0T8OgjAUBvCKjq6ewM2BQPyz6hUUeoAWSExDIDE4ewqvoNBLeAouwRmE58diQprY4PR16C9f-17KGJufpzFbxjLKL8khljs3SvNrLLLC8_zv2c2SIsVlRzC54DxUwhmyzW_WIy5XWldKTEYV9kjLPVFnSFsnEEn0Bob0LRIolErrUgk2lGuLBKrkjag1pK0TqMtm7MT53XivpRUsAEM8MSxjN5YJg5VgiDfRa-xmwVowxJHz-o9ufLhGPLRujJltrRofbhDYNGFq6gOYofZj",
          "sizes": {
            "active": 44475,
            "external": 1339,
            "file": 133970
          },
          "update_seq": "13-g1AAAALReJyd0T8OgjAUBvCKjq6ewM2BQPyz6hUUeoAWSExDIDE4ewqvoNBLeAouwRmE58diQprY4PR16C9f-17KGJufpzFbxjLKL8khljs3SvNrLLLC8_zv2c2SIsVlRzC54DxUwhmyzW_WIy5XWldKTEYV9kjLPVFnSFsnEEn0Bob0LRIolErrUgk2lGuLBKrkjag1pK0TqMtm7MT53XivpRUsAEM8MSxjN5YJg5VgiDfRa-xmwVowxJHz-o9ufLhGPLRujJltrRofbhDYNGFq6gOYofZj"
        },
        "key": "orders"
      }
    ]
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

    {
      "error": "not_found",
      "reason": "missing_named_view"
    }
  • 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 service unavailable.

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

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

    {
      "error": "bad_content_type",
      "reason": "Content-Type must be application/json"
    }
  • 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."
    }

Delete a database

Deletes the specified database and all documents and attachments contained within it. To avoid deleting a database, the server responds with a 400 HTTP status code when the request URL includes a ?rev= parameter. This response suggests that a user wanted to delete a document but forgot to add the document ID to the URL.

DELETE /{db}

Authorization

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

  • cloudantnosqldb.database.delete

Auditing

Calling this method generates the following auditing event.

  • cloudantnosqldb.database.delete

Request

Path Parameters

  • Path parameter to specify the database name.

    Possible values: length ≤ 238, Value must match regular expression ^_dbs$|^_global_changes$|^_metadata$|^_nodes$|^_replicator$|^_users$| ^[a-z][a-z0-9_$()+/-]*$

  • curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X DELETE "$SERVICE_URL/$DB_NAME"
  • deleteDatabaseOptions := service.NewDeleteDatabaseOptions(
      "<db-name>",
    )
    
    ok, response, err := service.DeleteDatabase(deleteDatabaseOptions)
    if err != nil {
      panic(err)
    }
    
    b, _ := json.MarshalIndent(ok, "", "  ")
    fmt.Println(string(b))
    
  • import com.ibm.cloud.cloudant.v1.Cloudant;
    import com.ibm.cloud.cloudant.v1.model.DeleteDatabaseOptions;
    import com.ibm.cloud.cloudant.v1.model.Ok;
    
    Cloudant service = Cloudant.newInstance();
    
    DeleteDatabaseOptions databaseOptions =
        new DeleteDatabaseOptions.Builder()
            .db("<db-name>")
            .build();
    
    Ok response =
        service.deleteDatabase(databaseOptions).execute()
            .getResult();
    
    System.out.println(response);
    
  • import { CloudantV1 } from '@ibm-cloud/cloudant';
    
    const service = CloudantV1.newInstance({});
    
    service.deleteDatabase({db: '<db-name>'}).then(response => {
      console.log(response.result);
    });
    
  • from ibmcloudant.cloudant_v1 import CloudantV1
    
    service = CloudantV1.new_instance()
    
    response = service.delete_database(db='<db-name>').get_result()
    
    print(response)
    

Response

Schema for an OK result.

Status Code

  • HTTP response for Ok operations.

  • HTTP response for errors.

Example responses
  • Example Ok response.

    {
      "ok": true
    }
  • Example error response for administrator privileges required.

    {
      "error": "unauthorized",
      "reason": "You are not a server admin."
    }
  • 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 database already existing.

    {
      "error": "file_exists",
      "reason": "The database could not be created, the file already exists."
    }
  • 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 database does not exist.

    {
      "error": "not_found",
      "reason": "Database does not exist."
    }
  • Example error response for a bad request missing keys.

    {
      "error": "bad_request",
      "reason": "`keys` member must exist."
    }
  • Example error response for a document update conflict.

    {
      "error": "conflict",
      "reason": "Document update conflict."
    }
  • Example error response for a document ID does not exist.

    {
      "error": "not_found",
      "reason": "missing"
    }
  • 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 missing view.

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

    {
      "error": "bad_request",
      "reason": "`counts` is not supported on this search index"
    }