Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 11 Next »

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 response object 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:

Pass the session_id value to the _session_id parameter in the URL, for example:

With the cURL command, use the -b and -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:

Use the -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.

 Expand source

Uploading photos

The create (POST) and update (PUT) methods for many objects such as UsersCheckins, and Photos take an optional photo or 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 photo or file must beimage/jpegimage/png, or image/gif.

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.

Object IDs

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:

Response paging


For query operations, the page and per_page paging mechanism described below only applies to applications created before ArrowDB 1.1.5. For applications created with ArrowDB 1.1.5 and later, you must use range-based queries, as discussed in Query Pagination.

API calls which return arrays of objects take optional page and 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 pageper_pagetotal_pages and total_results keys:

  • No labels