Using the REST API

Mobile Backend Services (MBS) provides a REST API accessible from any networked client device for creating, querying, updating, and deleting MBS objects.

Each MBS object supports a set of methods, which are documented in the API reference.

REST API basics

Each of the REST API methods has its 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 the message body, depending on the HTTP method.

For GET and DELETE requests, send the parameters in the URL 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 - An object containing response metadata, including the response status code and error message, if any.
• response - An object containing the actual data for the request. The response object is omitted for some requests, such as delete requests, that return no data.

Authentication

All API calls must contain a valid App Key or 2-Legged OAuth signature and request header for the MBS 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 that 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 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 if the user session expires, any MBS 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 MBS 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 MBS server. The --verbose option is useful for seeing all of the HTTP header and cookie information sent and received by the MBS server.

Uploading photos

The create (POST) and update (PUT) methods for many objects such as Users, Checkins, 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/jpeg, image/png, or image/gif.

When using cURL, uploading a photo can be done quickly 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 used to return data for a single object efficiently:

Response paging

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 page, per_page, total_pages, and total_results keys: