General Remarks¶

Request Headers¶

If not specified otherwise, all requests need some custom HTTP headers.

These are BaasBox Authentications headers, since the 0.5.7 version supports two authentication methods: HTTP Basic Authentication, or via a Session Token.

Basic Authentication¶

It needs to provide the user’s credentials via the basic access authentication method. Username and password must be combined into a string “username:password” and then encoded using BASE64. The header must be in the form: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== . If the authentication fails, the server replies with BAD REQUEST http error (code 400) X-BAASBOX-APPCODE: This is the application code, by default this is: 1234567890

Session Token¶

To use this authentication method, the client has to call the /users/login API. The Server will provide a token to use in the subsequent calls. All tokens will be invalidated if the server is stopped. To pass the session token to the server, use the following header:

X-BB-SESSION: 0000-1111-2222-3333

The JSON response¶

Every response generated by BaasBox as a result of a REST call is a JSON object with the following structure:

{

        "result": "ok|ko",

        "http_code": (200|201|204),

        "data": {

        ...the data themselves...

        }

}

In case of error, the data returned are more detailed and are useful to understand why the request was rejected. In this case, the JSON format is:

{

        "result": "error",

        "bb_code": xxx,

        "message": "...a message explaining the problem in plain English...",

        "resource": "...the REST API called....",

        "method": "...the HTTP method used...",

        "request_header": { .... the headers received by the server ...},

        "API_version": "...the BaasBox API version..."

}

For bb_code see below.

Custom Error Codes¶

These are custom error codes specific to BaasBox

• 40001: You are attempting to update a database object with older data. Version is not the same
• 40101: Invalid or not provided authentication info. HINT: Has your session expired?
• 50301: Push settings are not properly configured. HINT: go to administration console and check the settings
• 50302: The server cannot resolve the host name. HINT: check your internet connection
• 50303: Could not send push notifications. HINT: Check your API Key(Google)

Query Criteria¶

Some APIs allow to specify query criteria. Accepted parameters are:

• where: set a filter criteria in a SQL-like fashion (i.e.: “color=’yellow’ or address.city=’rome’”). It is possible to use the positional mode, for example: “color=? or address.city=?”. In this case you must supply the parameters’ values using the params querystring parameter. NOTE:the value of the parameter must be URL encoded.
• params: an array of value for the where clause. For example: /API\_URL/WHERECLAUSE/&params=yellow&params=cyan
• orderBy: set an order by clause in a SQL-like fashion (i.e.: orderBy name desc). NOTE: the direction of ordering (asc or desc) is mandatory if pagination is used (see below)
• page: a 0 based index indicating the page requested
• recordPerPage: the number of records per page
• fields: allow to specify a subset of fields (projections) to return instead of the entire record. It is also possibile to specify aggregate functions and execute all the operations allowed by OrientDB into the “select” statements. An exaustive list of available functions is available at https://github.com/orientechnologies/orientdb/wiki/SQL-Where#wiki-field-operators, meanwhile the explanation of how to specify projections is at https://github.com/orientechnologies/orientdb/wiki/SQL-Query#projections
• groupBy: allow to indicate a “group by” criteria to group the result-set by one or more fields just like in standard SQL statements. This criteria is used in conjunction with the aggregate functions expressed into the “fields”

Example of valid calls: /document/mycoolestcollection/count?where=color%3D’yellow’ /document/mycoolestcollection/count?where=color%3D%3F&params%3dyellow /document/documents/count?where=color%3D%3F%20or%20color%3D%3F&params=yellow&params=cyan