Objects API

Users API

Media API

Config API

Locale API

Emails API

Request Format

For POST and PUT requests, the request body must be JSON, with the Content-Type header set to application/json. BEA Engine accepts multiple encoded form values as well, with the Content-Type header set to multipart/form-data.

Authentication is done via HTTP headers. The X-BEA-Application-Id header identifies which application you are accessing, and the X-BEA-Authorization header authenticates the endpoint.

For JavaScript usage, the BEA Engine supports cross-origin resource sharing, so that you can use these headers in conjunction with XMLHttpRequest.

Response Format

The response format for all requests is a JSON object.

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure. When a request fails, the response body is still JSON, but always contains the fields code and error which you can inspect to use for debugging. For example, trying to save an object with invalid keys will return the message:

{ "code":105, "error":"invalid field name: bl!ng" }

Calling From Client Apps

You should not use the REST API Key in client apps (i.e. code you distribute to your customers). If the BEA SDK is available for your client platform, we recommend using our SDK instead of the REST API. If you must call the REST API directly from the client, you should use the corresponding client-side BEA Engine key for that plaform (e.g. Client Key for iOS/Android, or .NET Key for Windows/Xamarin/Unity).

If there is no BEA SDK for your client platform, please use your app’s Client Key to call the REST API. Requests made with the Client Key, JavaScript Key, or Windows Key are restricted by client-side app settings that you configure in your BEA Engine dashboard. These settings make your app more secure. For example, we recommend that all production apps turn off the “Client Push Enabled” setting to prevent push notifications from being sent from any device using the Client Key, JavaScript Key, or .NET Key, but not the REST API Key. Therefore, if you plan on registering installations to enable Push Notifications for your app, you should not distribute any app code with the REST API key embedded in it.

The JavaScript Key cannot be used to make requests directly against the REST API from JavaScript. The JavaScript Key is meant to be used with the BEA Engine JavaScript SDK, which makes its posts through a Cross Origin-friendly format without HTTP headers.

Object Format

Storing data through the BEA Engine REST API is built around a JSON encoding of the object’s data. This data is schemaless, which means that you don’t need to specify ahead of time what keys exist on each object. You simply set whatever key-value pairs you want, and the backend will store it.

For example, let’s say you’re tracking high scores for a game. A single object could contain:

{ "score": 1337, "playerName": "Sean Plott", "cheatMode": false }

Keys must be alphanumeric strings. Values can be anything that can be JSON-encoded.

Each object has a class name that you can use to distinguish different sorts of data. For example, we could call the high score object a GameScore. We recommend that you NameYourClassesLikeThis and nameYourKeysLikeThis, just to keep your code looking pretty.

When you retrieve objects from BEA Engine, some fields are automatically added: createdAt, updatedAt, and objectId. These field names are reserved, so you cannot set them yourself. The object above could look like this when retrieved:

{ "objectId": "Ed1nuqPvcm", "createdAt": "2011-08-20T02:06:57.931Z", "updatedAt": "2011-08-20T02:06:57.931Z", "score": 1337, "playerName": "Sean Plott", "cheatMode": false }

createdAt and updatedAt are UTC timestamps stored in ISO 8601 format with millisecond precision: YYYY-MM-DDTHH:MM:SS.MMMZ. objectId is a string unique to this class that identifies this object.

In the REST API, the class-level operations operate on a resource based on just the class name. For example, if the class name is GameScore, the class URL is:

 https://api.backendadmin.com/1/GameScore 

Users have a special class-level url:

 https://api.backendadmin.com/1/Users 

The operations specific to a single object are available as a nested URL. For example, operations specific to the GameScore above with objectId equal to Ed1nuqPvcm would use the object URL:

 https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

Creating Object

To create a new object on BEA Engine, send a POST request to the class URL containing the contents of the object. For example, to create the object described above:

 curl -X POST \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{"score":1337,"playerName":"Sean Plott","cheatMode":false}' \ https://api.backendadmin.com/1/GameScore 

When the creation is successful, the HTTP response is a 201 Created and the Location header contains the object URL for the new object:

 Status: 201 Created Location: https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

The response body is a JSON object containing the objectId and the createdAt timestamp of the newly-created object:

 { "createdAt": "2011-08-20T02:06:57.931Z", "objectId": "Ed1nuqPvcm" } 

Retrieving Object

Once you’ve created an object, you can retrieve its contents by sending a GET request to the object URL returned in the location header. For example, to retrieve the object we created above:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

The response body is a JSON object containing all the user-provided fields, plus the createdAt, updatedAt, and objectId fields:

 { "score": 1337, "playerName": "Sean Plott", "cheatMode": false, "skills": [ "pwnage", "flying" ], "createdAt": "2011-08-20T02:06:57.931Z", "updatedAt": "2011-08-20T02:06:57.931Z", "objectId": "Ed1nuqPvcm" } 

When retrieving objects that have pointers to children, you can fetch child objects by using the include option. For instance, to fetch the object pointed to by the “game” key:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'include=game' \ https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

Updating Object

To change the data on an object that already exists, send a PUT request to the object URL. Any keys you don’t specify will remain unchanged, so you can update just a subset of the object’s data. For example, if we wanted to change the score field of our object:

 curl -X PUT \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{"score":73453}' \ https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

The response body is a JSON object containing just an objectId field and an updatedAt field with the timestamp of the update.

 { "updatedAt": "2011-08-20T02:06:57.931Z", "objectId": "Ed1nuqPvcm" } 

 curl -X PUT \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{"score":"+=1"}' \ https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

 curl -X PUT \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{"score":"-=1"}' \ https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

 curl -X PUT \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{"skills":{"addUnique":"flying"}}' \ https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

 curl -X PUT \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{"opponents":{"addUnique":"Vx4nudeWn"}}' \ https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

 curl -X PUT \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{"opponents":{"remove":"Vx4nudeWn"}}' \ https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

Deleting Object

To delete an object from the BEA Engine, send a DELETE request to its object URL. For example:

 curl -X DELETE \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ https://api.backendadmin.com/1/GameScore 

When the deletion is successful, the HTTP response is a 201 Created and the Location header contains the object URL for the new object:

 Status: 201 Deleted Location: https://api.backendadmin.com/1/GameScore/Ed1nuqPvcm 

The response body is a JSON object containing the objectId field only:

 { "objectId": "Ed1nuqPvcm" } 

Batch Operations

To reduce the amount of time spent on network round trips, you can create, update, or delete up to 50 objects in one call, using the batch endpoint.

Each command in a batch has method, path, and body parameters that specify the HTTP command that would normally be used for that command. The commands are run in the order they are given. For example, to create a couple of GameScore objects:

 curl -X POST \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{ "requests": [ { "method": "POST", "path": "/GameScore", "body": { "score": 1337, "playerName": "Sean Plott" } }, { "method": "POST", "path": "/GameScore", "body": { "score": 1338, "playerName": "ZeroCool" } } ] }' \ https://api.backendadmin.com/1/batch 

The response from batch will be a list with the same number of elements as the input list. Each item in the list with be a dictionary with either the success or error field set. The value of success will be the normal response to the equivalent REST command:

 { "results": [ { "createdAt": "2012-06-15T16:59:11.276Z", "objectId": "YAfSAWwXbL" } ] } 

The value of error will be an object with a numeric code and error string:

 { "error": { "code": 101, "error": "object not found for delete" } } 

Other commands that work in a batch are update, get and delete.

 curl -X POST \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -d '{ "requests": [ { "method": "GET", "path": "/GameScore", "body": { "fields": "playerName,score", "limit": 100 } }, { "method": "PUT", "path": "/GameScore/Ed1nuqPvcm", "body": { "score": 999999 } }, { "method": "DELETE", "path": "/GameScore/Cpl9lrueY5" } ] }' \ https://api.backendadmin.com/1/batch 

Note that N requests sent in a batch will still count toward your request limit as N requests.

Data Types

So far we have only used values that can be encoded with standard JSON. The BEA Engine client libraries also support dates, geolocations, relational data, and more. In the REST API, these values are encoded as JSON hashes with the __type field set to indicate their type, so you can read or write these fields if you use the correct encoding. Overall, the following types are allowed for each field in your object:

• String
• LongText
• Number
• Integer
• Email
• Key
• Data
• Color
• Boolean
• Date
• Time
• Password
• Options
• Array
• Pointer (Pointer to another Class Object
• PointerArray (Relation to another Class Objects)
• GEOPoint
• DateTime
• JSON Objects
• File
• Null

The Date type contains a field iso which contains a UTC timestamp stored in ISO 8601 format with millisecond precision: YYYY-MM-DDTHH:MM:SS.MMMZ.

Dates are useful in combination with the built-in createdAt and updatedAt fields. For example, to retrieve objects created since a particular time, just encode a Date in a comparison query:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'where={"createdAt":{"gte":{"2011-08-21T18:02:52.249Z"}}}' \ https://api.backendadmin.com/1/GameScore 

The Pointer type is used when code sets another Class Object as the value of another object. It contains the className and objectId of the referred-to value.

Note that the built-in Config and Locale classes are prefixed by an underscore. Prefixing with an underscore is forbidden for developer-defined classes as it signifies the class is a special built-in.

The PointerArray type is used for many-to-many relations. It has a className that is the class name of the target objects.

When querying, PointerArray objects behave like arrays of Pointers. Any operation that is valid for arrays of pointers (including include) works for PointerArray objects.

We do not recommend storing large pieces of binary data like images or documents on a BEA Engine object. To store more, we recommend you use File or the built in Media system within each class. You may associate a previously uploaded file using the File type.

When more data types are added, they will also be represented as hashes with a __type field set, so you may not use this field yourself on JSON objects. For more information about how BEA Engine handles data, check out our documentation on Data.

Basic Queries

You can retrieve multiple objects at once by sending a GET request to the class URL. Without any URL parameters, this simply lists objects in the class:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ https://api.backendadmin.com/1/GameScore 

The return value is a JSON object that contains a results field with a JSON array that lists the objects.

 { "results": [ { "playerName": "Jang Min Chul", "updatedAt": "2011-08-19T02:24:17.787Z", "cheatMode": false, "createdAt": "2011-08-19T02:24:17.787Z", "objectId": "A22v5zRAgd", "score": 80075 }, { "playerName": "Sean Plott", "updatedAt": "2011-08-21T18:02:52.248Z", "cheatMode": false, "createdAt": "2011-08-20T02:06:57.931Z", "objectId": "Ed1nuqPvcm", "score": 73453 } ] } 

Query Constraints

There are several ways to put constraints on the objects found, using the where URL parameter. The value of the where parameter should be encoded JSON. Thus, if you look at the actual URL requested, it would be JSON-encoded, then URL-encoded. The simplest use of the where parameter is constraining the value for keys. For example, if we wanted to retrieve Sean Plott’s scores that were not in cheat mode, we could do:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'where={"playerName":"Sean Plott","cheatMode":false}' \ https://api.backendadmin.com/1/GameScore 

The values of the where parameter also support comparisons besides exact matching. Instead of an exact value, provide a hash with keys corresponding to the comparisons to do. The where parameter supports these options:

For example, to retrieve scores between 1000 and 3000, including the endpoints, we could issue:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'where={"score":{"gte":1000,"lte":3000}}' \ https://api.backendadmin.com/1/GameScore 

To retrieve scores equal to an odd number below 10, we could issue:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'where={"score":{"in":[1,3,5,7,9]}}' \ https://api.backendadmin.com/1/GameScore 

To retrieve scores not by a given list of players we could issue:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'where={ "playerName": { "": [ "Jonathan Walsh", "Dario Wunsch", "Shawn Simon" ] } }' \ https://api.backendadmin.com/1/GameScore 

To retrieve documents with the score set, we could issue:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'where={"score":{"exists":true}}' \ https://api.backendadmin.com/1/GameScore 

To retrieve documents without the score set, we could issue:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'where={"score":{"exists":false}}' \ https://api.backendadmin.com/1/GameScore 

If you have a class containing sports teams and you store a user’s hometown in the user class, you can issue one query to find the list of users whose hometown teams have winning records. The query would look like:

 curl -X GET \ -H "X-BEA-Application-Id: sd2312" \ -H "X-BEA-Authorization: REST_API_KEY123123" \ -H "Content-Type: application/json" \ -G \ --data-urlencode 'where={"hometown":{"select":{"query":{"className":"Team","where":{"winPct":{"gt":0.5}}},"field":"city"}}}' \ https://api.backendadmin.com/1/GameScore 

In addition to where, there are several parameters you can use to configure what types of results are returned by the query.

Basic Queries

Basic Queries

Basic Queries

Basic Queries

Basic Queries

Basic Queries