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:

Take a look at the BEA Engine Feaures to learn more about the different features and usecases.
  • 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.

Want to contribute to this doc? Edit this section.
Was this section helpful? NO YES Thanks for your feedback, we’re always working to make our docs better.

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>//<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.

Want to contribute to this doc? Edit this section.
Was this section helpful? NO YES Thanks for your feedback, we’re always working to make our docs better.

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
  • 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.

Want to contribute to this doc? Edit this section.
Was this section helpful? NO YES Thanks for your feedback, we’re always working to make our docs better.

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:

KeyOperation
startswithValue starts with
notstartswithValue do not start with
endswithValue ends with
notendswithValue do not end with
startswithValue starts with
ltLess Than
lteLess Than Or Equal To
gtGreater Than
gteGreater Than Or Equal To
eqEqual To
equalsExactly Equals To (case sensitive)
neNot Equal To
notequalsNot Equal To (case sensitive)
likeLike
notlikeNot Like
inContained In
ninNot Contained in
existsA value is set for the key
selectThis matches a value for a key in the result of a different query
dontSelectRequires that a key’s value not match a value for a key in the result of a different query
allContains all of the given values
regexRequires 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.

Basic Queries

Basic Queries

Basic Queries

Basic Queries

Basic Queries

Basic Queries

Want to contribute to this doc? Edit this section.
Was this section helpful? NO YES Thanks for your feedback, we’re always working to make our docs better.
Rest |