General Remarks¶

Request Headers¶

If not specified otherwise, all requests need some custom HTTP headers. These are Authentications headers BaasBox, since the 0.57 version supports two authentication method: HTTP Basic Authentication, or via a Session Token.

BASIC AUTHENTICATION Authorization 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 have to call the /users/login API. The Server will provide a token to use in the subsequent calls. If not used, the token will expire in 15 minutes. All tokens will be invalidated if the server is stopped. To pass the session token to the server, use the following header: X-BB-SESSIONExample: 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": "",

    "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 [[here|Custom Error Code]]

Query Criteria Some APIs allow to pass query criteria via QueryString. 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 that case you must supply the parameters’ values using the ‘params’ query string parameter. NOTE:the value of the parameter must be URLEncoded.
• 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

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