Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Manage Deployments with the Management API v4.0

  • Capella Operational
  • concept
    +
    The Couchbase Capella Management API is a secure REST API that enables you to provision, deploy, and configure Capella deployments across all supported cloud service providers.

    This page is for Capella. For Capella columnar, see Manage Deployments with the Columnar Management API.

    Clients do not need any special tools, SDKs, or libraries to access the Management API. The Management API supports off-the-shelf HTTP clients, such as Insomnia or Postman.

    To get started quickly, create an API key and make an API call.

    Versioning

    The Management API v4.0 uses semantic versioning. The full version number consists of three parts: major.minor.patch.

    An update to the Management API may be a non-versioned bug fix, a patch update, a minor update, or a major update. When a non-versioned bug fix is released, the version number is not updated. When a patch update, a minor update, or a major update is released, the version number is updated also.

    With few exceptions, new versions of Management API are backward compatible, minimizing the impact to existing deployments. In most cases, you are not required to update your existing infrastructure when a new version of the Management API is released. Features added in a new version of the Management API will not break existing deployments.

    Exceptions to backward compatibility are as follows:

    • Critical security fixes. A vulnerable version is marked as unsupported when a fixed version is released. In this case, you must plan to upgrade as soon as possible.

    • Fundamental architectural changes, when unavoidable.

    Deprecation of Previous Versions

    The Management API v4.0 supersedes the Management API v3.0, and all previous versions. The Management API v3.0 and earlier was formerly known as the Public API. The Management API v3.0 is deprecated, and will be removed in future. Users of the Management API v3.0 must plan to migrate to the Management API v4.0.

    Authentication and Authorization

    The Management API v4.0 uses API keys for authentication and authorization. Please note that you need new API keys to access endpoints exposed by the Management API v4.0.

    API keys that were created for the Management API v3.0 or earlier cannot be used with the Management API v4.0 or later.

    API keys are associated with Couchbase Capella roles and permissions. An API key must have the appropriate Capella roles to access an endpoint. The Management API reference guide lists the roles that are needed for each endpoint.

    Every API key is associated with an allowed IP Address list, which can be configured during API key creation. Every API key has an expiration date.

    To authenticate a Management API call, the API key must be passed as a Bearer token using the HTTP Authorization header.

    Concurrent Access and PUT Requests

    To support concurrent requests, PUT requests support optimistic concurrency control, using If-Match headers in combination with HTTP ETags (entity tags). Exceptions are noted in the endpoint descriptions. A typical pattern is to do a GET request on a specified resource, which returns an ETag value. You can then include the ETag value in a PUT request to update the resource.

    PUT requests ignore all fields in the body of the request that are not required. Required fields for each PUT request are specified in the Management API reference guide.

    Auditing

    All requests to the Management API are audited. All endpoints support Audit fields for audit purposes, except where noted in the Management API reference guide.

    Lists are paginated.

    Service Limits

    Long-Running Requests

    The following long-running requests are rejected with error 504, Gateway Timeout:

    • Read requests taking longer than 90 seconds to process.

    • Write requests taking longer than 120 seconds to process.

    Rate Limiting

    Requests are limited to 100 requests per minute per API key.

    Payload Size

    Requests and response payloads are restricted to 18 MB.

    See Also