REST API

The Couchbase Lite REST API provides HTTP access to your databases. This introduces the REST API and includes an overview of the available resources.

Notation Conventions

Within the paths of the URIs presented in these guides:

• Path segments that start with an underscore character are static components of the URI that you use exactly as given. For example: _replicate.

• Path segments that are not preceded by an underscore character represent variables that you replace with your own value. These variables are usually enclosed in brackets as a reminder. For example: {db} or <db>.

For example, suppose you have a database named cookbook. In the database, the IDs for recipes start with the string "recipe" and IDs for design documents start with the string "ddoc". The following table shows examples of values you might use for the URI path in the request that you send to the database:

HTTP requests and responses

The Couchbase Lite REST API uses the Hypertext Transfer Protocol (HTTP). Each API is an HTTP request. For each HTTP request that you send, you receive an HTTP response. HTTP requests consist of a request line, header lines, and a message body. HTTP responses consist of a status line, header lines, and a message body.

The examples in this document are shown in the basic HTTP format.

The message body for both the HTTP requests and HTTP responses is formatted as a JSON document. To learn more about JSON, check out JSON.org or the W3Schools JSON Tutorial.

Each HTTP response contains a status code. The following table lists some of the status codes returned by Couchbase Lite:

• Server

  

  APIs that operate at the server level

  • GET /
  • GET /_active_tasks
  • GET _all_dbs
  • POST _replicate
  • GET /_session
  • GET /_uuids

• Database

  

  APIs that operate on databases

  • PUT /{db}
  • GET /{db}
  • DELETE /{db}
  • GET /{db}/_all_docs
  • POST /{db}/_all_docs
  • POST /{db}/_bulk_docs
  • GET /{db}/_changes
  • POST /{db}/_compact
  • POST /{db}/_purge
  • POST /{db}/_temp_view

• Document

  

  APIs that operate on documents

  • POST /{db}
  • PUT /{db}/{doc}
  • GET /{db}/{doc}
  • DELETE /{db}/{doc}
  • PUT /{db}/{doc}/{attachment}
  • GET /{db}/{doc}/{attachment}
  • DELETE /{db}/{doc}/{attachment}

• Local Document

  

  APIs that operate on local documents

  • PUT /{db}/{local-doc-id}
  • GET /{db}/{local-doc-id}
  • DELETE /{db}/{local-doc-id}

• Design Document

  

  APIs that operate on design documents

  • PUT /{db}/{design-doc-id}
  • GET /{db}/{design-doc-id}
  • DELETE /{db}{design-doc-id}
  • GET /{db}{design-doc-id}/{attachment}
  • PUT /{db}/{design-doc-id}/{attachment}
  • DELETE /{db}/{design-doc-id}/{attachment}
  • GET /{db}/{design-doc-id}/_view/{view-name}
  • POST /{db}/{design-doc-id}/_view/{view-name}

• Authentication

  

  APIs that authenticate users

  • POST /_facebook_token
  • POST /_persona_assertion