Guide: REST

TABLE OF CONTENTS

3. The REST API

TouchDB's intrinsic API, like CouchDB's, is based on HTTP and 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 not normally used by mobile or desktop applications: instead they use a more convenient native CouchDB wrapper API such as CouchCocoa on iOS/Mac OS, or Ektorp on Android. However, the principles of it are useful to know.

One interesting difference is at the very top level of the URLs: the scheme itself. CouchDB of course uses the http: or https: schemes. TouchDB doesn't communicate with your app over HTTP sockets because it's already built into the app; instead it fakes it by registering a custom touchdb: 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 TouchDB 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 TouchDB to handle it.

1. Everything has a URL. Databases, documents and attachments all have their own URLs. And the URLs form a hierarchy, using the IDs as components of the path. So for example, the URL touchdb:///mydb/doc1/readme.txt refers to the attachment readme.txt of the document doc1 in the database mydb. (Revisions have URLs too, but they're not quite as clean: to name a specific revision of a document, a ?rev= query parameter is added.)
2. PUT and POST create documents. A PUT to the URL of a nonexistent document creates it. A POST to a database URL creates a new document with a randomly-generated UUID for its ID.
3. GET reads a document. A GET of a document's URL returns the current revision in JSON form, including its current revision ID in the _rev property. A ?rev= query parameter can be added to access a specific revision.
4. PUT updates a document. But as described above, the new document body needs to include an _rev_ property that matches the document's current revision (the same property value that came back from a GET), otherwise it'll be rejected as a conflict.
5. DELETE deletes a document. Just like a PUT, it needs to supply the current _rev or it'll be rejected.

There's a lot more to the API, from creating databases to accessing special metadata to defining views, but it's largely irrelevant unless you want to use REST directly. If you want to know the details, the API reference on the CouchDB wiki is the best place to dive in (or if you're the toe-dipping type, the aforementioned CouchDB: The Definitive Guide covers much of it in tutorial style.)

NEXT: How TouchDB Differs From CouchDB