REST API Overview

From Clusterpoint Wiki
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.

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.

API access (cloud)

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

https://api.clusterpoint.com/

Request methods and URIs

Requests on particular documents

General document URIs are formed in the following way:

https://<server>/<account id>/<database name>/<docid>/[.format]

where:

<server> is the hostname of the CPS2 server

<account id> cloud account ID

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

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

[format] (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.

If parameter is placed in "<..>" brackets, than it is mandatory, if "[..]" brackets are used, than - optional.

Permitted request methods

API understands the following methods:

GET
retrieves the document's contents if <docid> is presented, if not - retrieves database status
POST
inserts created document or execute advanced command if <command> is presented
PUT
replaces existing document with content submitted in HTTP POST data
DELETE
deletes the document
HEAD
checks whether the document exists

Sample request and response

This example fetches document with ID 1 in JSON:

GET https://api.clusterpoint.com/17/Test3/1
HTTP/1.0 200
Server: nginx/1.6.2
Date: Wed, 04 Mar 2015 08:55:51 GMT
Content-Type: application/json, charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
CPS-seconds: 0.0008

{
    "1":{
        "id":"1",
        "Amount":"200"
    }
} 

Note the CPS-seconds header which returns the amount of time it took for the database 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

https://<server>/<account id>/<database name>/<command>/<parameters>[.format]?[optional-parameters]

where:

<server> is the hostname of the CPS2 server

<account id> cloud account ID

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

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

[.format] (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 "Technique" in XML:

POST https://api.clusterpoint.com/17/Test3/_search/Technique/10/.xml
HTTP/1.0 200
Server: nginx/1.6.2
Date: Thu, 05 Mar 2015 07:50:48 GMT
Content-Type: text/xml, charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
CPS-seconds: 0.0025

<?xml version="1.0" encoding="utf-8"?>
<content>
<document>
	<id>16</id>
	<Category>Technique</Category>
</document>
<document>
	<id>20</id>
	<Category>Technique</Category>
</document>
</content>

Available commands

Available commands in the REST API are:

Basic Commands Request method URI
Status GET https://<server>/<account id>/<database name>[.<format>]
Update PUT https://<server>/<account id>/<database name>/<docid>[.<format>]
Update (multiple) PUT https://<server>/<account id>/<database name>[.<format>]
Insert POST https://<server>/<account id>/<database name>/<docid>[.<format>]
Inser (multiple) POST https://<server>/<account id>/<database name>[.<format>]
Delete DELETE https://<server>/<account id>/<database name>/<docid>[.<format>]
Document exists HEAD https://<server>/<account id>/<database name>/<docid>
Retrieve GET https://<server>/<account id>/<database name>/<docid>[.<format>]


Advanced Commands Request method URI
Replace POST https://<server>/<account id>/<database name>/_replace[.<format>]
Partial-replace POST https://<server>/<account id>/<database name>/_partial_replace[.<format>]
Delete POST https://<server>/<account id>/<database name>/_delete[.<format>]
Lookup (multiple) POST https://<server>/<account id>/<database name>/_lookup[.<format>]
Retrieve (multiple) POST https://<server>/<account id>/<database name>/_retrieve[.<format>]
Search POST https://<server>/<account id>/<database name>/_search/<query>[/<documents>[/<offset>]][.<format>]
List-last POST https://<server>/<account id>/<database name>/_list_last[/<documents> [/<offset>]][.<format>]
List-first POST https://<server>/<account id>/<database name>/_list_first[/<documents> [/<offset>]][.<format>]
Retrieve-last POST https://<server>/<account id>/<database name>/_retrieve_last[/<documents>[/<offset>]][.<format>]
Retrieve-first POST https://<server>/<account id>/<database name>/_retrieve-first[/<documents>[/<offset>]][.<format>]

Samples of requests and responses

Replace: replaces an existing document (JSON):

POST https://api.clusterpoint.com/17/Test3/_replace/68.json
HTTP/1.0 200
Server: nginx/1.6.2
Date: Thu, 05 Mar 2015 08:19:24 GMT
Content-Type: application/json, charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
CPS-seconds: 0.0057

[
    "ok: 68"
]


Retrieve: returns a document with the specified ID from the database (XML):

GET https://api.clusterpoint.com/17/Test3/28.xml
HTTP/1.0 200
Server: nginx/1.6.2
Date: Thu, 05 Mar 2015 08:48:17 GMT
Content-Type: text/xml, charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
CPS-seconds: 0.0008

<?xml version="1.0" encoding="utf-8"?>
<content>
<document>
	<id>28</id>
	<Category>Calculating</Category>
</document>
</content>

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"}