ArrowDB provides a REST API accessible from any networked client device for creating, querying, updating, and deleting ArrowDB objects.
Each ArrowDB object supports a set of methods, which are documented in the API reference.
REST API basics
Each of the REST API methods has its own URL and HTTP method (GET, POST, PUT, or DELETE).
To make an API call, you make an HTTP request. Method parameters are passed in the URL query string or in the message body, depending on the HTTP method.
For GET and DELETE requests, send the parameters in the URL itself as part of the URL query string. For example:
For POST and PUT requests, you send an HTTP request with the
multipart/form-data media type, where each parameter is sent as a separate form field.
API responses are returned as JSON objects. In most cases, the response JSON includes two objects:
meta -Object containing response metadata, including the response status code and error message, if any.
response -Object containing the actual data for the request. The
responseobject is omitted for some requests, such as delete requests, that return no data.
All API calls must contain a valid App Key or 2-Legged OAuth signature and request header for the ArrowDB server to process and respond to them. See the authentication page for more information.
User sessions and cookies
To create a user and perform actions which require a logged-in user, the
session_id cookie must be saved and reused with each API call.
To get a session ID, use the
users/login.json method to login in to the application. If the API call is successful, the
session_id field is returned in the
meta object of the response. For example:
session_id value to the
_session_id parameter in the URL, for example:
With the cURL command, use the
-c options to read and write cookies to store your session ID. Many of the REST examples in the documentation use these options.
User login sessions expire after they have been unused for three months. If the application saves and uses a persistent reference to the user login session, and the user session expires, any ArrowDB call that requires a user login will return a 404 error. Your application needs to handle an invalid user session error, such as prompting the user to log in.
Testing with cURL and wget
cURL and wget are both excellent tools for quickly testing ArrowDB API calls from the command line. Using these commands can help you determine what calls to make and show you the JSON output that your app receives. cURL is included with OS X, and can easily be used from the Terminal application:
-b cookies.txt and
-c cookies.txt options to save and reuse the
_session_id cookie sent from the ArrowDB server. The
--verbose option is useful for seeing all of the HTTP header and cookie information sent and received by the ArrowDB server.
create (POST) and
update (PUT) methods for many objects such as
Photos take an optional
file parameter to send a photo. The binary data must be sent in a form with Content-Type
multipart/form-data, and the content type of the
file must be
When using cURL, uploading a photo can be done easily by using
@ in front of the filename, such as
@photo.jpg, to specify that the file should be attached.
All returned data objects contain unique IDs which are 24-digit hexadecimal strings. These IDs may be use to efficiently return data for a single object:
API calls which return arrays of objects take optional
per_page arguments to specify the number of objects to return. By default, ten objects are returned on each page, and the request may specify up to 20 results per page. Page numbers start at 1; if unspecified, the page defaults to page 1.
Data about the current page is included in the
meta object. For paged responses, the
meta object includes the