Getting Started
The REST API lets you interact with BEA Engine from anything that can send an HTTP request like web and mobile apps, or any other Internet connected device. There are many things you can do with the REST API. For example:
- A mobile website can access BEA Engine data from JavaScript.
- A webserver can show data from BEA Engine on a website.
- You can upload large amounts of data that will later be consumed in a mobile app.
- You can download recent data to run your own custom analytics.
- Applications written in any programming language can interact with data on BEA Engine.
- You can export all of your data if you no longer want to use BEA Engine.
Quick Reference
API access is provided over HTTPS and WSS exclusively, and accessed via the https://api.backendadmin.com
URL. We recommend utilizing HTTPS for anything other than local development. The relative path prefix /1/
indicates that we are currently using version 1 of the API.
Objects API
URL | HTTP Verb | Functionality |
---|---|---|
/1/<className> | POST | Creating Objects |
/1/<className>/<objectId> | GET | Retrieving Objects |
/1/<className>/<objectId> | PUT | Updating Objects |
/1/<className> | GET | Queries |
/1/<className>/<objectId> | DELETE | Deleting Objects |
Users API
URL | HTTP Verb | Functionality |
---|---|---|
/1/Users | POST | Signing Up |
/1/Users/login | GET | Logging In |
/1/Users/logout | POST | Logging Out |
/1/Users/<objectId> | GET | Retrieving Users |
/1/Users/me | GET | Retrieving Current User |
/1/Users/<objectId> | PUT | Updating Users |
/1/Users | GET | Querying Users |
/1/Users/<objectId> | DELETE | Deleting Users |
/1/Users/requestPasswordReset | POST | Requesting A Password Reset |
Media API
URL | HTTP Verb | Functionality |
---|---|---|
/1/<className>/ | POST | Uploading/Adding Files |
/1/<className>/<objectId>/ | GET | Retrieving Media For Objects |
/1/<className>/<objectId>/ | DELETE | Deleting Media For Objects |
Config API
URL | HTTP Verb | Functionality |
---|---|---|
/1/_config | POST | Add Parameter |
/1/_config/<objectId> | GET | Retrieving Parameters |
/1/_config/<objectId> | PUT | Updating Parameters |
/1/_config | GET | Querying Parameters |
/1/_config/<objectId> | DELETE | Deleting Parameters |
Locale API
URL | HTTP Verb | Functionality |
---|---|---|
/1/_locale | POST | Add Key/Values |
/1/_locale/addLang | POST | Adding a new Language |
/1/_locale/<objectId> | GET | Retrieving Key/Values |
/1/_locale/<objectId> | PUT | Updating Key/Values |
/1/_locale | GET | Querying Key/Values |
/1/_locale/<objectId> | DELETE | Deleting Key/Values |
Emails API
URL | HTTP Verb | Functionality |
---|---|---|
/1/_emails | POST | Add Email |
/1/_emails/send | POST | Sending An Email |
/1/_emails/<objectId> | GET | Retrieving Emails |
/1/_emails/<objectId> | PUT | Updating Emails |
/1/_emails | GET | Querying Emails |
/1/_emails/<objectId> | DELETE | Deleting Emails |
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.
Objects
...
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" }
Counters
To help with storing counter-type data, BEA Engine provides the ability to atomically increment (or decrement) any number field. So, we can increment the score field like so:
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
To decrement the counter, use the -=
operator at the begining as a string value:
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
Arrays
To help with storing array data, there are three operations that can be used to atomically change an array field:
add
appends the given array of objects to the end of an array field.addUnique
adds only the given objects which aren’t already contained in an array field to that field. The position of the insert is not guaranteed.remove
removes all instances of each given object from an array field.
Each method takes an array of objects to add or remove in the “objects” key. For example, we can add items to the set-like “skills” field like so:
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
Relations
In order to update Relation
types, BEA Engine provides special operators to atomically add and remove objects to a relation. So, we can add an object to a relation like so:
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
To remove an object from a relation, you can do:
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
- 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.
Queries
...
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:
Key | Operation |
---|---|
startswith | Value starts with |
notstartswith | Value do not start with |
endswith | Value ends with |
notendswith | Value do not end with |
startswith | Value starts with |
lt | Less Than |
lte | Less Than Or Equal To |
gt | Greater Than |
gte | Greater Than Or Equal To |
eq | Equal To |
equals | Exactly Equals To (case sensitive) |
ne | Not Equal To |
notequals | Not Equal To (case sensitive) |
like | Like |
notlike | Not Like |
in | Contained In |
nin | Not Contained in |
exists | A value is set for the key |
select | This matches a value for a key in the result of a different query |
dontSelect | Requires that a key’s value not match a value for a key in the result of a different query |
all | Contains all of the given values |
regex | Requires that a key’s value match a regular expression |
arraykey | -- |
arraykeyall | -- |
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.