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.

Integrating the Data API with Cloud Native Gateway

  • concept
How to integrate with the Data API served by Cloud Native Gateway, including authentication, document operations, and service passthrough.

Connecting to the Data API

Cloud Native Gateway serves the Data API over HTTPS on the Data API port. The base URL depends on your deployment:

All requests require TLS. If Cloud Native Gateway uses a self-signed certificate for development, you must configure your HTTP client to trust it or turn off certificate verification.

Authentication

Include an Authorization header with every request:

$ curl -u Administrator:password \
    https://cng.example.com:18099/v1/callerIdentity

The callerIdentity endpoint verifies that authentication is working:

{
  "user": "Administrator"
}

Document Operations

This section describes the core actions you can perform with documents via the API, including retrieval, updates, and related workflows.

Retrieving a Document

Retrieve returns the current document for the specified key if it exists.

$ curl -u user:pass \
    https://cng.example.com:18099/v1/buckets/travel-sample/scopes/_default/collections/_default/documents/airline_10

Response:

{
  "id": 10,
  "type": "airline",
  "name": "40-Mile Air",
  "iata": "Q5",
  "icao": "MLA",
  "callsign": "MILE-AIR",
  "country": "United States"
}

The response headers include:

  • ETag — The CAS value for optimistic concurrency control.

  • X-CB-Flags — The document’s encoding flags.

Retrieving Specific Fields

Retrieving specific fields returns only the requested fields for the specified document key. Use the project query parameter to retrieve only specific fields:

$ curl -u user:pass \
    "https://cng.example.com:18099/v1/buckets/travel-sample/scopes/_default/collections/_default/documents/airline_10?project=name,country"

Inserting a Document

Insert creates a new document for the specified key only if it does not already exist.

$ curl -X POST -u user:pass \
    -H "Content-Type: application/json" \
    -d '{"type": "hotel", "name": "Test Hotel", "city": "London"}' \
    https://cng.example.com:18099/v1/buckets/travel-sample/scopes/_default/collections/_default/documents/hotel_test_1

This fails with a 409 Conflict if the document already exists.

Upserting a Document

Upsert creates the document if it does not exist or replaces it if it does.

$ curl -X PUT -u user:pass \
    -H "Content-Type: application/json" \
    -d '{"type": "hotel", "name": "Updated Hotel", "city": "Paris"}' \
    https://cng.example.com:18099/v1/buckets/travel-sample/scopes/_default/collections/_default/documents/hotel_test_1

Removing a Document

Remove deletes the document for the specified key if it exists.

$ curl -X DELETE -u user:pass \
    https://cng.example.com:18099/v1/buckets/travel-sample/scopes/_default/collections/_default/documents/hotel_test_1

Optimistic Concurrency with CAS

CAS applies the mutation only if the document’s current CAS matches the If-Match value from the earlier read. Use the ETag header from a GET response as the If-Match header on a subsequent mutation to verify the document has not changed:

$ curl -X PUT -u user:pass \
    -H "Content-Type: application/json" \
    -H "If-Match: \"1234567890\"" \
    -d '{"type": "hotel", "name": "Concurrent Update"}' \
    https://cng.example.com:18099/v1/buckets/travel-sample/scopes/_default/collections/_default/documents/hotel_test_1

If the document changed since the GET, the server returns 409 Conflict.

Service Passthrough

The /_p/ prefix proxies requests to Couchbase service REST APIs.

Executing a SQL++ Query

$ curl -X POST -u user:pass \
    -H "Content-Type: application/json" \
    -d '{"statement": "SELECT name, city FROM `travel-sample` WHERE type = \"hotel\" LIMIT 5"}' \
    https://cng.example.com:18099/_p/query/query/service

Executing a Search Service

$ curl -X POST -u user:pass \
    -H "Content-Type: application/json" \
    -d '{
      "query": {"match": "London", "field": "city"},
      "size": 5
    }' \
    https://cng.example.com:18099/_p/fts/api/index/travel-sample-index/query

The passthrough proxy forwards requests to the appropriate Couchbase service using Cloud Native Gateway’s cluster credentials with On-Behalf-Of semantics. Cloud Native Gateway checks the request against the calling user’s permissions.

Error Handling

The Data API returns standard HTTP status codes with JSON error bodies:

HTTP Status Error Code Description

400

InvalidArgument

The request contains invalid parameters or a malformed body.

401

Unauthenticated

Authentication credentials are missing or invalid.

403

Forbidden

The authenticated user does not have sufficient permissions.

404

DocumentNotFound

The requested document does not exist.

409

AlreadyExists / CasMismatch

Document already exists on insert, or CAS mismatch on conditional update.

429

Rate limited

Request rate limit exceeded.

500

Internal

An internal error occurred.