Guide: REST

TABLE OF CONTENTS

8. The REST API

Couchbase Lite supports an optional HTTP-based API interface. This API is compatible with Apache CouchDB's and allows access to nearly all TouchDB functionality through HTTP requests. This is useful for a couple of reasons:

1. To support embedded web-apps that access the REST APU through AJAX (these are commonly called "CouchApps"). These can easily be packaged up into native apps using a host like PhoneGap.
2. To enable apps written in other languages like C#, which have CouchDB APIs available that can communicate with the REST API.
3. To support peer-to-peer replication between apps on two devices, over WiFi.

The HTTP API follows the architectural style known as REST (Representational State Transfer), in which resources identified by URLs act as "objects" and the basic HTTP verbs act as "methods". This maps very well to the fundamental create / read / update / delete (CRUD) operations of a database. It's also similar to the read-write extension of HTTP, WebDAV.

I won't go into the exact details of the API, because it's documented elsewhere. The API reference on the CouchDB wiki is the best place to dive in, and the book CouchDB: The Definitive Guide covers much of it in tutorial style.

Enabling The REST API

The code that handles this API isn't in the core Couchbase Lite library, for size reasons. Instead it's in an additional framework called CouchbaseLiteListener. You'll need to link this into your app too to use the REST API.

Once you've done this, you can call the method -internalURL on the top-level CBLManager instance, or on any CBLDatabase instance, to get its equivalent URL. You can then derive other entities' URLs relative to it and send them requests.

One interesting difference from CouchDB is at the very top level of the URLs: the scheme itself. CouchDB of course uses the http: or https: schemes. Couchbase Lite doesn't communicate with your app over TCP sockets because it's already built into the app; instead it fakes it by registering a custom cbl: scheme. As long as your app uses the platform-standard URL access API (NSURLConnection on iOS or Mac OS), it can make HTTP request using this scheme instead of http: and they'll be routed directly to the Couchbase Lite thread. However if you make HTTP requests from WebKit (such as from a PhoneGap app) WebKit will only include the message body if you use a standard http: or https: scheme. In this case you can use a URL with a standard scheme and a host name ending with .touchdb. for Couchbase Lite to handle it.

Serving The REST API

If you want external clients to be able to connect to the REST API, to enable peer-to-peer replication, you'll need to instantiate a CBLListener object.

#import <CouchbaseLiteListener/CBLListener.h>

CBLManager* manager = [CBLManager sharedInstance];
_listener = [[CBLListener alloc] initWithManager: manager port: 0];
BOOL ok = [_listener start];
UInt16 actualPort = _listener.port;  // the actual TCP port it's listening on

NEXT: How Couchbase Lite Differs From CouchDB