Make an API Call with the Management API v4.0

how-to

How to make an API call with the Management API v4.0.

Prerequisites

In order make an API call with the Management API v4.0, you must have an API key that was created for the Management API v4.0. API keys for the Management API v3.0, formerly known as the Public API, are not compatible with the Management API v4.0.

The API key must have all the organization roles, project access, and project roles required to carry out the API call. Note that in the Management API v4.0 reference, each endpoint description lists the roles that are needed.
The API key must not have expired.
The API key must grant access to the Management API from your client’s IP address.
You must have saved the API key token when you created it.

To create an API key for the Management API v4.0, see Get Started with the Management API v4.0.

Make an API Call

You can use a client such as cURL or a native SDK call to make an API call with the Management API.

To make an API call:

Use the following base URL.

https://cloudapi.cloud.couchbase.com
Pass the API key as a Bearer token using the HTTP Authorization header.
If a request body is required, pass it in JSON format.

Alternatively, you can use a client such as Insomnia or Postman to explore the details of the REST API, generate code samples, and so on. The Management API v4.0 uses an OpenAPI v3 specification. To download the Management API v4.0 specification, go to the Management API Reference and click Download.

Examples

List Organizations

The following request lists all of the organizations available to the provided API key.

$BASEURL is the base URL for the API call.
$TOKEN is the API key token.

HTTP Request

curl "$BASEURL/v4/organizations" \
   -H "Authorization: Bearer $TOKEN"

The response is a JSON object similar to the following. In this case, the provided API key is able to access a single organization.

HTTP Response

{
  "data": [
    {
      "audit": {
        "createdAt": "2020-07-22T12:38:57.437248116Z",
        "createdBy": "",
        "modifiedAt": "2023-07-25T14:33:56.13967014Z",
        "modifiedBy": "<redacted>",
        "version": 0
      },
      "description": "",
      "id": "<redacted>",
      "name": "cbc-dev",
      "preferences": {
        "sessionDuration": 7200
      }
    }
  ]
}

Note that the response includes the organization ID. You can use the organization ID for any further API calls in which {organization} is a path parameter.

List Projects in an Organization

The following request lists all of the projects available to the provided API key within the specified organization.

$BASEURL is the base URL for the API call.
$ORGID is the organization ID.
$TOKEN is the API key token.

The query parameters specify that each page of results should contain 3 projects, and that the request should return the first page of results.

HTTP Request

curl "$BASEURL/v4/organizations/$ORGID/projects?perPage=3&page=1" \
   -H "Authorization: Bearer $TOKEN"

The response is a JSON object similar to the following.

HTTP Response

{
  "cursor": {
    "hrefs": {
      "first": "http://<BASEURL>/v4/organizations/<ORGID>/projects?page=1&perPage=3",
      "last": "http://<BASEURL>/v4/organizations/<ORGID>/projects?page=182&perPage=3",
      "next": "http://<BASEURL>/v4/organizations/<ORGID>/projects?page=2&perPage=3",
      "previous": ""
    },
    "pages": {
      "last": 182,
      "next": 2,
      "page": 1,
      "perPage": 3,
      "previous": 0,
      "totalItems": 544
    }
  },
  "data": [
    {
      "audit": {
        "createdAt": "2023-08-07T10:58:04.844838072Z",
        "createdBy": "<redacted>",
        "modifiedAt": "2023-08-07T10:58:04.844855439Z",
        "modifiedBy": "<redacted>",
        "version": 1
      },
      "description": "",
      "id": "<redacted>",
      "name": "Project 1"
    },
    {
      "audit": {
        "createdAt": "2023-08-30T10:52:25.834748195Z",
        "createdBy": "<redacted>",
        "modifiedAt": "2023-08-30T10:52:25.83476043Z",
        "modifiedBy": "<redacted>",
        "version": 1
      },
      "description": "terraform testing",
      "id": "<redacted>",
      "name": "Project 2"
    },
    {
      "audit": {
        "createdAt": "2023-07-18T09:28:13.334086299Z",
        "createdBy": "",
        "modifiedAt": "0001-01-01T00:00:00Z",
        "modifiedBy": "",
        "version": 0
      },
      "description": "",
      "id": "<redacted>",
      "name": "Project 3"
    }
  ]
}

Note that this response contains cursor information, showing the pagination of the results. For each project, audit information is provided, showing metadata for the project.

Get Details of a Project

The following request gets details about the specified project within the specified organization.

$BASEURL is the base URL for the API call.
$ORGID is the organization ID.
$PROJECTID is the project ID.
$TOKEN is the API key token.

HTTP Request

curl "$BASEURL/v4/organizations/$ORGID/projects/$PROJECTID" \
   -H "Authorization: Bearer $TOKEN"

The response is a JSON object similar to the following.

HTTP Response

{
  "audit": {
    "createdAt": "2023-03-14T15:12:25.671401417Z",
    "createdBy": "<redacted>",
    "modifiedAt": "0001-01-01T00:00:00Z",
    "modifiedBy": "",
    "version": 0
  },
  "description": "",
  "id": "<redacted>",
  "name": "Project 1"
}

Update a Project

The following request updates the specified project within the specified organization with a new description.

$BASEURL is the base URL for the API call.
$ORGID is the organization ID.
$PROJECTID is the project ID.
$TOKEN is the API key token.

HTTP Request

curl -X PUT "$BASEURL/v4/organizations/$ORGID/projects/$PROJECTID" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{"name": "Project 1", "description": "New description"}'

In this example, only the description field is new. However, both the name and description fields are required, so the name field is supplied unchanged.

Get the ETag for a Project

The following request gets the ETag of the specified project within the specified organization.

$BASEURL is the base URL for the API call.
$ORGID is the organization ID.
$PROJECTID is the project ID.
$TOKEN is the API key token.

HTTP Request

curl "$BASEURL/v4/organizations/$ORGID/projects/$PROJECTID" -i \
   -H "Authorization: Bearer $TOKEN" | grep etag

Note that cURL also has an --etag-save option, which provides a convenient way of saving the ETag value. This example requests the protocol response headers instead, for clarity.

The response is an ETag similar to the following.

HTTP Response

etag: 1

You can use the ETag in a PUT request for concurrency control.

Update a Project with Concurrency Control

The following request checks whether the specified project within the specified organization has the expected ETag. If so, it updates the project with a new description.

This enables you to make sure that you are applying your update to the correct revision of the project, in cases where the project may be updated by other processes concurrently.

$BASEURL is the base URL for the API call.
$ORGID is the organization ID.
$PROJECTID is the project ID.
$TOKEN is the API key token.

HTTP Request

curl -X PUT "$BASEURL/v4/organizations/$ORGID/projects/$PROJECTID" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -H "If-Match: 1" \
   -d '{"name": "Project 1", "description": "Updated description"}'

Note that cURL also has an --etag-compare option, which provides a convenient way of checking the ETag value. This example specifies the If-Match request header instead, for clarity.

If the ETag of the project matches, the project is updated. If the ETag does not match, the request returns an error message similar to the following.

HTTP Response

{
  "code": 9000,
  "hint": "Please include the correct ETag version with the request.",
  "httpStatusCode": 412,
  "message": "Unable to process update. The 'ETag' provided does not match the current version of the document being requested to update."
}

Next Steps

For a full reference guide, see Management API v4.0 Reference.
For an error reference, see Management API v4.0 Errors.