Table of Contents
The Couchbase REST API enables you to manage a Couchbase Server deployment as well as perform operations such as storing design documents and querying for results. The REST API conforms to Representational State Transfer (REST) constraints, in other words, the REST API follows a RESTful architecture. You use the REST API to manage clusters, server nodes, and buckets, and to retrieve run-time statistics within your Couchbase Server deployment. If you want to develop your own Couchbase-compatible SDK, you will also use the REST-API within your library to handle views. Views enable you to index and query data based on functions you define. For more information about views, see Chapter 9, Views and Indexes.
The REST API should not be used to read or
write data to the server. Data operations such
asset and get for example,
are handled by Couchbase SDKs. See
Couchbase SDKs.
The REST API accesses several different systems within the Couchbase Server product.
Please provide RESTful requests; you will not receive any handling instructions, resource descriptions, nor should you presume any conventions for URI structure for resources represented. The URIs in the REST API may have a specific URI or may even appear as RPC or some other architectural style using HTTP operations and semantics.
In other words, you should build your request starting from Couchbase Cluster URIs, and be aware that URIs for resources may change from version to version. Also note that the hierarchies shown here enable your reuse of requests, since they follow a similar pattern for accessing different parts of the system.
The REST API is built on a number of basic principles:
JSON Responses
The Couchbase Management REST API returns many responses as JavaScript Object Notation (JSON). On that node, you may find it convenient to read responses in a JSON reader. Some responses may have an empty body, but indicate the response with standard HTTP codes. For more information, see RFC 4627 (http://www.ietf.org/rfc/rfc4627.txt) andwww.json.org.
HTTP Basic Access Authentication
The Couchbase Management REST API uses HTTP basic authentication. The browser-based Chapter 6, Using the Web Consoleand Chapter 7, Command-line Interface for Administrationalso use HTTP basic authentication.
Versatile Server Nodes
All server nodes in a cluster share the same properties and can handle any requests made via the REST API.; you can make a REST API request on any node in a cluster you want to access. If the server node cannot service a request directly, due to lack of access to state or some other information, it will forward the request to the appropriate server node, retrieve the results, and send the results back to the client.
In order to use the REST API you should be aware of the different terms and concepts discussed in the following sections.