REST API Overview

From ClusterpointWiki2

Jump to: navigation, search

For programming languages, which don't have a native CPS API implemented, the REST API provides easy access to CPS by exchanging data in JSON or XML. This page explains how this API can be used.

Keep in mind, that REST API doesn't implement the full feature set of Clusterpoint Server, however it is very easy to use, and thus is a good starting point for getting to know CPS. If you feel you are missing some vital functionality that is available in Clusterpoint Server, but is not available through the REST API, let us know and we will consider implementing it into the REST API in future versions of Clusterpoint Server.

Contents

Required configuration

First of all, you should follow the installation instructions for your particular distribution closely. Your Apache web-server has to include the following directive in its configuration:

AllowOverride Limit FileInfo

The mod_rewrite Apache module has to be enabled as well.

If you are using a different web-server, refer to your web server's manual for instructions on how to configure functionality similar to mod_rewrite.

REST API authorization

By default the REST API uses the default root/password login and password pair. It is possible to submit your own login and password through Basic HTTP authorization. Alternatively, if you would like to use different authentication credentials, but don't want to submit them every time with each request, you can change the default login and password in the rest.cfg.php file, which is usually located under /usr/local/cps2/cps2_active/management/cpsam/rest/

API access

By default, REST API is available at the following URL:

http://<server>/cps2/rest/

In case you will be moving the cps2 interface or the REST API to a different URL, make sure to edit the RewriteBase directive in the /usr/local/cps2/cps2_active/management/cpsam/rest/.htaccess file, to reflect the new relative URI for the REST interface.

If you open this URL in a browser, you will be redirected to the REST API Test screen, where all the supported REST API commands can be sent through an HTML form.

Request methods and URIs

Requests on particular documents

General document URIs are formed in the following way:

http://<server>/cps2/rest/<storage name>/<docid><optional-type>

where:

<server> is the hostname of the CPS2 server

<storage name> is the name of the storage you are trying to access

<docid> is the document ID that you are referring to

<optional-type> (optional) is either ".json" or ".xml". If you don't specify the type and don't send any extra content, the API will return JSON. If you send XML or JSON content, the API will respond in the same format that you sent the request data in.

Permitted request methods

API understands the following methods:

PUT
creates the document or replaces the existing document with content submitted in HTTP POST data (update command)
POST
merges the document with the submitted content (partial-replace)
DELETE
deletes the document (delete)
HEAD
checks whether the document exists (lookup)
GET
retrieves the document's contents (retrieve)

Sample request and response

This example fetches document with ID 1 in JSON:

GET http://127.0.0.1/cps2/rest/test/1


HTTP/1.1 200 OK
Date: Wed, 07 Mar 2012 16:09:10 GMT
Server: Apache/2.2.17 (Linux/SUSE)
X-Powered-By: PHP/5.3.5
CPS-seconds: 0.0002
Content-Length: 27
Keep-Alive: timeout=15, max=99
Connection: Keep-Alive
Content-Type: application/json, charset=utf-8

{"id":"1", "title":"Title"} 

Note the CPS-seconds header which returns the amount of time it took for the storage to process the request.

Other requests

Operations that aren't linked to a particular document are usually performed over the GET request method and generally (status is a notable exception) their URIs have the form of

http://<server>/cps2/rest/<storage name>/<command>/<parameters><optional-type>?<optional-parameters>

where:

<server> is the hostname of the CPS2 server

<storage name> is the name of the storage you are trying to access

<command> is the command that you are willing to execute, prepended by an underscore ("_") symbol

<optional-type> (optional) is either ".json" or ".xml". If you don't specify this, the API will return JSON.

<parameters> and <optional-parameters> differ for each command.

Sample request and response

This example fetches at most 10 documents that match the query "title" in XML:

GET http://127.0.0.1/cps2/rest/_search/title/10.xml


HTTP/1.1 200 OK
Date: Thu, 07 Mar 2012 16:46:46 GMT
Server: Apache/2.2.17 (Linux/SUSE)
X-Powered-By: PHP/5.3.5
CPS-seconds: 0.0007
Content-Length: 201
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
Content-Type: text/xml, charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<content>
  <document>
    <id>docid1</id>
    <title>Title 1</title>
  </document>
  <document>
    <id>docid2</id> 
    <title>Title 2</title>
  </document>
</content>

Available commands

Available commands in the REST API are:

Command Request method URI more info
Status GET http://<server>/cps2/rest/<storage name> REST Status
Update PUT http://<server>/cps2/rest/<storage name>/<docid> REST Update
Insert (auto-increment only) POST http://<server>/cps2/rest/<storage name> REST Insert
Partial-replace POST http://<server>/cps2/rest/<storage name>/<docid> REST Partial-Replace
Delete DELETE http://<server>/cps2/rest/<storage name>/<docid> REST Delete
Lookup HEAD http://<server>/cps2/rest/<storage name>/<docid> REST Lookup
Retrieve GET http://<server>/cps2/rest/<storage name>/<docid> REST Retrieve
Search GET http://<server>/cps2/rest/<storage name>/_search/<query>/<optional-docs> REST Search
List-last, List-first, Retrieve-last, Retrieve-first GET http://<server>/cps2/rest/<storage name>/_list_last/<optional-docs> REST List-Last

Error handling

Errors are generally returned in the form of HTTP error codes. Their meaning is deciphered below

HTTP Code Error message Meaning
200 OK The request was completed successfully - no error
400 Bad Request The request was malformed
401 Unauthorized The login/password, specified in the config file or submitted over HTTP Basic Authentication was incorrect or the user didn't have permission to run the particular operation
404 Not Found The document does not exist
405 Method Not Allowed An unknown method request is used
415 Unsupported Media Type Couldn't parse submitted XML or JSON
500 Internal Server Error The server responded to the request with an error
503 Service Unavailable No response received from server

In addition to HTTP codes, the text of the error message is returned in the following structure:

for XML:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <error>error text</error>
</response>

for JSON:

{"error":"error text"}
Personal tools
Namespaces
Variants
Actions
Download
Developer area
Admin area
Product manuals
Toolbox
Navigation