REST API

The LiteCoreREST library adds a small embedded HTTP server to LiteCore, which implements a subset of the Couchbase Lite 1.x (and Sync Gateway and CouchDB and Cloudant and PouchDB) REST API. You can easily run this by using the cblite tool's serve subcommand.

Again, this is not the full REST API; it doesn't expose all functionality, it's not enough for Cordova/PhoneGap, and it's not enough for compatibility with the 1.x (or CouchDB or PouchDB) replicator. But it has some uses:

• Automated testing of LiteCore
• Load testing of Sync Gateway (by starting a bunch of cblite serve processes to replicate with it)
• Automated creation of Couchbase Lite 2 database files from a server, to be bundled into apps

(If you want to cross-reference with the actual code, look at where the handlers are registered in RESTListener.cc.)

API

Method	Path	Parameter	Description
GET	/		Server info, like the version
GET	/_all_dbs		List of all database names
POST	/_replicate		Start a replication; parameters in JSON body (see below)
GET	/_active_tasks		Info on active replications and waiting _changes feeds
GET	/db		Database doc count, current sequence, etc.
DELETE	/db		Deletes a database
PUT	/db		Creates a database
POST	/db		Creates a document with an automatically generated UUID
GET	/db/_all_docs		List of documents including current revID
		?descending=true	Reverses sort order (descending docID)
		?include_docs=true	Adds body of each doc
		?limit=	Limits number of results
		?skip=	Skips initial results
POST	/db/_bulk_docs		Creates/updates/deletes multiple documents
GET	/db/_changes		Changes feed (CBL 3.3+)
		?since=	Start after this sequence number
		?feed=	Feed type: "normal" (default), "longpoll", "continuous"
		?limit=	Limits number of changes returned
		?include_docs=true	Adds doc bodies to results
		?active_only=true	Suppresses deleted documents
		?descending=true	Reverses sort order (descending sequence)
POST	/db/_query		N1QL/SQL++ query (see below) (CBL 3.3+)
GET	/db/id		Returns document body
		?rev=revID	Revision ID to get (optional)
DELETE	/db/id		Deletes a document
		?rev=revID	Current revision ID (required)
PUT	/db/id		Creates or updates a document
		?rev=revID	Current revision ID (required if doc exists, unless you add a _rev property to the JSON body)

Scopes & Collections

Following Sync Gateway's lead, the way to access a non-default collection is to append it to the /db path component, with a dot in between. If it's in a non-default scope, the scope goes before the collection, again separated by a dot.

For example: GET /dbname.mycollection/mydoc, or GET /dbname.myscope.mycollection/mydoc

Queries (/db/_query)

Properties of the JSON request body:

• query: The N1QL/SQL++ query string. The FROM clause must match the database name or be _.
• params: An object mapping query parameter names (without the $) to values. Omit if there are no parameters.

Replication (/_replicate)

Properties of the JSON request body:

• source: Required! The source database
• target: Required! The destination database
• bidi: Set to true for bidirectional push/pull replication
• continuous: Set to true for continuous replication
• collections: Optional array of collection names
• cancel: Set to true to stop an active replication with the same parameters
• user: Username for HTTP Basic auth to remote server
• password: Password for HTTP Basic auth to remote server

Either source or target must be a local database name; the other must be a remote ws: or wss: sync URL.

Missing Stuff

• All HTTP endpoints and "?" options not listed above
• Access to revision history
• Attachments
• MIME multipart formats (good riddance!)
• Local-to-local replication (where both source and target are local db names)