Introduction

BaasBox is a complete solution to implement the back end of your applications.

It is available as a product released under the Apache 2 license

The latest version is 0.9.4

You can access all sections using the sidebar on the left. The documentation explains:

• the BaasBox features (server side)

  • how to install BaasBox
  • how to use the admin console and a detailed section about the REST API that you can use
  • REST API
  • Plugin Engine (Server Side Scripts)

• the SDK features

  • iOS SDK
  • Android SDK
  • JavaScript

For a complete list of changes and new features, see the changelog

The Android SDK JavaDoc is here

Our tutorials will allow you to rapidly have a first result of what BaasBox can give you. Enjoy!

1
2

In this section you can find code examples for every platform we address.
Click on any tab above to choose the platform of your interest.

1
2
3
4
5
6
7
8
9

You have two ways to install the iOS SDK.
We suggest cocoapods: just add "pod 'BaasBoxSDK', '~> 0.9.0'" to your pod file.
As an alternative you can download this repo (https://github.com/baasbox/iOS-SDK) and drag and drop the BaasBox-iOS-SDK folder on Xcode.

Finally insert the following statement wherever you need BaasBox functionalities
#import "BAAClient.h"
and you are good to go.

Note for Swift projects. As of Xcode 6.1 you need to drag .h and .m files (and not the enclosing folder), otherwise you are not asked to create a bridging header. Once you have created one, add the following statement and you are good to go: #import "BAAClient.h"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

/*
The Android SDK is distributed as a jar.
To get started download it from the download section of the website
(https://opensource.bassbox.com/), and put it in your libs folder.

To initialize the client, add the following code to your application
class.
*/

public class MyApp extends Application{
  private BaasBox client;

  @Override
  public void onCreate() {
    BaasBox.Builder builder = new BaasBox.Builder(this);
    client =builder.setApiDomain("127.0.0.1")
                   .setAppCode("YOUR-APP-CODE")
                   .init();
  }
}

1
2
3
4
5
6
7
8
9
10
11
12

/*
You can download the SDK from the [download page](https://opensource.baasbox.com).
To use the SDK just import jQuery and the `baasbox.js` in the head section of your page like this.
*/

<script src="http://code.jquery.com/jquery-1.9.1.min.js"></script> 
<script src="../baasbox.js"></script>

/*
The jQuery cookie plugin, needed to save authentication tokens, is already included at the top of the `baasbox.js` file.
The SDK also supports [Zepto](http://zeptojs.com/).
*/

Installation

System Requirements Java VM 8 or later. BaasBox is compiled with Java 1.8.

1. Download the latest version here.
2. Unzip the baasbox-x.x.zip file wherever you want.
3. Type:
   • run start.bat (on Windows)
   • ./start (on *nix) You might need to grant execution permissions via chmod +x ./start

BaasBox will start and it will listen on port 9000. Visit http://localhost:9000/ with your preferred browser. If everything worked fine, the BaasBox logo should appear. Now you can open the administrator console: http://localhost:9000/console For further details about the console, you can read console. That’s all! BaasBox is ready to go and to serve your apps! To stop the server just halt (Ctrl-C) the shell script.

BaasBox is also available as a cloud service already configured and ready to use.

Configuration

BaasBox does not need any configuration to start. However, you can modify many parameters to fit your specific needs. You can act on different setting levels depending on your goal. The setting levels are:

• JVM parameters

• Play Framework settings

• BaasBox settings

• App settings

To set an option you have to type it as a start script parameter.

JVM Parameters

1

./start -XX:MaxPermSize=64m

1

NOTHING HERE. See the 'Shell' Tab

1

NOTHING HERE. See the 'Shell' Tab

1

NOTHING HERE. See the 'Shell' Tab

Since BaasBox runs on top of a Java Virtual Machine, you can use any JVM options to perform a fine tuning of your BaasBox. By default no options are used. A complete reference to the JVM parameters can be found here.

These settings cannot be modified at runtime.

Play Framework Settings

1

./start -Dhttp.port=80

1

NOTHING HERE. See the 'Shell' Tab

1

NOTHING HERE. See the 'Shell' Tab

1

NOTHING HERE. See the 'Shell' Tab

BaasBox is based on the Play Framework 2.2.4. This means that it accepts all the options available for any Play application. A complete reference of such options can be found here.

These settings cannot be modified at runtime.

BaasBox Settings

There are some settings relating to a specific instance of the BaasBox server, such as, for example, the AppCode. The AppCode is a special code that must be supplied every time an API call is executed. These settings cannot be modified at runtime.

Here are the BaasBox settings you can set:

These settings cannot be modified at runtime.

App Settings

These are the settings relating to your App. They are stored into the embedded DB and because of this, once they are set, they are read from the DB and you do not have to specify them every time you start BaasBox. The App Settings can be configured via the Administration Console. The settings are split in five sections:

• Application

• Password Recovery

• Images

• Push Notifications

• Social Login

These settings can be modified at runtime.

The available options for each section are described below.

Application

General options for the App(lication)

Password Recovery

Options for the Password Recovery feature

Images

Options for the server-side images resizing feature

Push Notifications

Since version 0.8.4, with BaasBox is possible to manage at most three apps for sending push notifications.
i.e. an administration app and a customer app for a store, or it’s possible to distribute one app for free and one app not for free. In this example the apps share the same backend.

New section on console, Push Settings available directly in leftmenu.

N.B.: Apps must be turned on after being configured

Options for the Push Notifications feature

Social Login

Options to use the Social Networks as user authenticators

Override App Settings

1

./start -Dbaasbox.settings.Application.session_tokens.timeout.value=30

The options and settings defined into the database can be overridden providing new values through CLI parameters.

The stored values are not modified.

To override a specific setting:

baasbox.settings.<section>.<key>.value=<new value>

Where

• section is one of:

  • Application
  • PasswordRecovery
  • Push
  • Social
  • Images

• key is one of the keys listed above

Both sections and key names are case-sensitive.

External Configuration File

Instead of passing every single option as a parameter of the start script, you can put all of them in an external file and simply tell BaasBox where this is located.

To use an external file, you have to use the following options and instructions

Regarding the config.file key, a possible example of an external configuration file may be:

1
2
3
4
5

include classpath("application.conf")

application.code="1234-56789"

orient.baasbox.path=db/baasbox

1

NOTHING HERE. See the 'Shell' Tab

1

NOTHING HERE. See the 'Shell' Tab

1

NOTHING HERE. See the 'Shell' Tab

General Overview

BaasBox is a server that makes available a set of functions for the backend of mobile applications. All you need is a Java Virtual Machine 1.8 or later. BaasBox already has everything you need for it to work: an application server and a DB server. BaasBox was born to be simple to use and manage. To migrate a BaasBox instance from a server to another, you just have to zip the database folder and copy it into the server target folder. Moreover, it is ready to use without changing the configuration parameters. You just have to launch the command ./start (or start.bat on Windows) and BaasBox will run. Should you need it, you can apply customized configuration parameters. See the configuration section.

Available Functions

Available functions are:

• Administration console:

  • A convenient web based administration console is provided, through which the administrator can manage several features of BaasBox

• Content management:

  • Definition of “objects collection (AKA documents)”
  • Creation, modification and deletion of objects
  • Granting and revoking reading/modification/cancellation authorization on single objects
  • Queries that allow specifying selection and ordering criteria
  • Management of “special” contents called Assets, which may be files of any kind, to which you can associate arbitrary JSON data

• Users management:

  • Signup, Login, Logout, profile management (private features, public features and so on), forgotten password recovery, link and log-in through Facebook and Google+
  • Role management: administrators, registered users, back-office users, creation of new roles.

• File management:

  • Create and fetch files
  • Content and metadata extraction
  • ACL
  • Images resize

• Push notifications:

  • Push notifications for iOS and Android devices

• DB management:

  • Backup/restore and reset the integrated database

• REST API Access management:

  • Enable/disable groups of REST endpoints from external access

Applied Technology

BaasBox is written mostly in Java, with some code in Scala. It uses the Play Framework 2.2.4 and it incorporates the core of the OrientDB 1.7.10 database. This will allow BaasBox to natively manage the relations between JSON objects and to link objects and queries without using specific abstractions or having to simulate them on the applicative level. OrientDB was recently surveyed and entered Gartner’s Magic Quadrant.

Console

1
2
3
4
5
6
7

To run the BaasBox server go into its folder and type
./start
on Windows systems type
start.bat

Once the server is up and running, you can access the console by opening the following link:
http://127.0.0.1:9000/console

1

NOTHING HERE. See the 'Shell' Tab

1

NOTHING HERE. See the 'Shell' Tab

1

NOTHING HERE. See the 'Shell' Tab

BaasBox has a web console that allows to manage its behavior and to perform administrative tasks. The console is a responsive one-page web application that performs REST calls to the BaasBox admin APIs. We suppose that BaasBox is deployed on localhost with its default parameters. If you deployed BaasBox the correct way, you can open your browser and open the welcome screen:

Login screen

When you are in the start view, the administrator console is reachable at the /console path.

To login in the administrative area you must supply credentials and Application Code to the administrator. By default these values are:

• Username: admin
• Password: admin
• App Code: 1234567890

You can change the App Code at any time by following the instructions shown in the configuration section. By clicking on the question marks, the fields will be filled with the default values.

Dashboard

Once you have logged in, you will see the main dashboard screen:

The web console is based on the Twitter bootstrap and on the Charisma Template project. The dashboard is split into several sections:

1. BaasBox version number
2. Quick link to the BaasBox site
3. Main menu to access all the main sections of BaasBox
4. A trace of where you are located
5. Number of users and rapid access to the relative section
6. Number of documents (objects) stored in the embedded database and rapid access to the relative section
7. Number of files stored and rapid access to the relative section
8. Quick link to the download on the BaasBox website where you can find the latest version
9. Number of collections, documents and total size in one window.
10. Here you can see all the latest news about BaasBox. These are feeds from the BaasBox site |News|
11. System window:
    • Memory: you can find max allocable memory, current allocated memory and current used memory
    • OS: you can find name, version, architecture and processors viewed by your OS
    • Java: you can find version, vendor and class version of your JDK
    • Database: you can find the version with its path and data size
12. Access a dialog window to change the password or to logout
    • Change password: Just insert old and new passwords, then confirm the new one
    • Logout: just logout from the console. Remember that you can also logout from the left menu.
13. DB Management: you can create a backup of your DB and import & export
14. Roles: you can view and create roles for users
15. Files: here you will find the files you have uploaded and you will be able to manage them and work on them
16. REST API Access: The REST API Access section allows you to manage which REST endpoints are accessible to non administrator users
17. Push. The section where it is possible to enable/disable apps to send push notifications. You can also test your settings sending test messages to registered users
18. Plugin installed. The section where it is possibile to write your own plugins.
19. See the BaasBox verbose log. Useful to inspect what happens behind the scene and to report detailed bugs

Console settings

By selecting the Settings option in the left menu you can access the settings section. You can choose settings for applications, password recovery, images and push notifications. Each record has the Edit button that allows you to modify its action. See also Settings.

Image resizing

In the settings you can define an array of possible resizing policies for images.

Examples are:

• 25% : scales the image to 25%
• <=80px: scales the image so that the smallest dimension is at most 80px.

See Retrieve a file on how to use these values.

REST API Access

The REST API Access section allows you to manage which REST endpoints are accessible to non administrator users. Those are grouped by functionality under a Function group. Each record has a button to switch on and off the endpoints in the named group.

Database Management

The item DB Management allows you to perform some operations on the database.

1. Restore a previously created backup file
2. Create a new backup
3. View the list of generated backups
4. Reinitialize the database at its initial state. It deletes all the database content.

To create a new backup, you have to click on the “Create a new backup…” button. This operation is asynchronous. BaasBox will freeze the database and it will stop responding to the clients. When the backup is ready you will find it in the list. From that list you can download it or delete it.

To restore a database you have to download a backup file locally, and then use the restore feature.

Server Log

By clicking on this menu item, a new window (or tab) will be opened in your web browser. In this new window, from now on, you will see the BaasBox verbose log (not available on the BaasBox cloud service). This feature is quite useful to know what happens behind the scene without access to the server to inspect the logs.

Push Settings

The Push Settings section allows you to enable/disable apps for sending push notifications. From BaasBox 0.8.4 it is possible to manage apps for sending push notifications. In particular BaasBox support max three apps. It’s possible to switch app settings by the tab section.

• App #1 (Default) is the section for the first app, which is the default app
• App #2 is the section for the second app
• App #3 is the section for third app

For Android Key (Sandbox/Production), remember to check the availability of Google Cloud Messaging for Android, in Google Play Developer Console. If disabled or if Android Key is wrong it will be returned error and no key are stored.

When the settings is configured, is possible to enabled the specific app.

Notice: Is possible to switch mode, with app enabled, only if the settings for the other mode are configured.

Push Test

From here you can send messages and test the API to send push notifications. By default the Payload is:

1
2
3
4

{
    "users": ["user1","user2"],
    "message": "This is a test message!"
}

Into the Server Response section you can see detailed information on which steps BaasBox performed to elaborate the provided JSON.

Users

By selecting the Users option on the menu you can access the users section.

In this section you have the list of all users. A single user has a name, a role (admin, anonymoususer, backofficeuser, registereduser), a creation date, a status and actions. You also have a search tool. If you want to create a new user, click on the New User button and you will see this window:

Collections

By selecting the Collections option on the menu you can access the collection administration page. Collections are a sort of buckets where you can store objects, also known as “documents”.

In this section you have a list of all your collections and you can quickly find them with the search tool. To create a new collection, click on the New Collection button and insert its name, then save the changes.

Documents

Documents are objects stored in the embedded NoSQL database and grouped in “Collections”.

In this section you have the list of all your documents, but you have to select an existing collection at first. In fact you can see all the documents relating to a specific collection. Of course you also have the search tool.

Each document has a unique ID, generated by the server once it is stored. Data documents are stored and retrieved JSON format.

Documents are accessible only by the user who created them. APIs exist to grant and revoke permissions to the single users or roles. See also Grant/Revoke.

Assets

Assets are special objects. They are public by default, but only administrators can create or delete them. They can store arbitrary data (in JSON format), or entire files. Each Asset can store a file and its associated data. Assets do not have IDs generated by the server, but you can, indeed you MUST, assign a unique name to them. You can subsequently use these names to reference the assets.

In this section you have a detailed list of all your assets with information fields like Icon, Name, Meta, Size, Type, Download and Actions. Of course you also have the search tool. If you want to create a new asset, click on the New Asset button and you will see the following window:

Plugins

Since BaasBox 0.9.0 it is possibile to write your own plugin thanks to the Server Side Code (engine).

The home of the plugins section is the following:

To create a new plugin, click on the “New…” button and choose a plugin name.

The names of the plugins must be in the form namespace.plugin_name, the namespace “baasbox” is reserved.

Now you have created a new plugin, here is a brief explanation of the editor page.

1. Create a new plugin
2. Delete the plugin
3. Refresh the plugin list
4. Save the plugin
5. Activate/deactivate the plugin
6. Show/Hide the plugin local storage
7. Edit the plugin (you can enter edit mode just by starting to type)
8. Enable/Disable the Plugin Log

For further information please check the wiki

SDK

Native SDKs for iOS, Android and Javascript are available. They allow to access to many functions of BaasBox server using a native interface.

One cool feature it is the “pass through” function that allow to perform a raw call to BaasBox in case you want to do something that is not supported by the SDK yet.

iOS SDK

The SDK is distributed in two ways:

• as a Cocoapod
• as a zip file

We recommend to install it using Cocoapods. Just add the following line to your Podfile.

pod 'BaasBoxSDK', '~> 0.9.0'

If you prefer the good old way, download the SDK from the download section of the website, and drag and drop the whole folder into your Xcode project.

Finally insert the following statement wherever you need BaasBox functionalities

#import "BAAClient.h"

and you are good to go.

Note for Swift projects. As of Xcode 6.1 you need to drag .h and .m files (and not the enclosing folder), otherwise you are not asked to create a bridging header.

Initialization

You need to initialize the SDK before making any API call. The best place to do it is in the `application:didFinishLaunchingWithOptions method of your app. All you need to provide is the base URL and the app code, as in the example on the right.

1
2

[BaasBox setBaseURL:@"http://localhost:9000"
appCode:@"1234567890"];

1

NOTHING HERE. See the 'iOS' Tab

1

NOTHING HERE. See the 'iOS' Tab

1

NOTHING HERE. See the 'iOS' Tab

Architecture and pass-through

The iOS SDK is structured following an onion-skin model. Most of the APIs are available through classes like BAAUser or BAAObject, which respectively contains methods for user management (login, signup, etc.) and documents (create, update, etc.). We suggest you use these methods when available. Should you see “TO BE IMPLEMENTED” in the iOS section, you can resort to use the BAAClient class. On the right there is an example of a GET request.

There are four methods, one for each HTTP verb.

- (void)getPath:(NSString *)path parameters:(NSDictionary *)parameters success:(void (^)(id responseObject))success failure:(void (^)(NSError *error))failure;

- (void)postPath:(NSString *)path parameters:(NSDictionary *)parameters success:(void (^)(id responseObject))success failure:(void (^)(NSError *error))failure;

- (void)putPath:(NSString *)path parameters:(NSDictionary *)parameters success:(void (^)(id responseObject))success failure:(void (^)(NSError *error))failure;

- (void)deletePath:(NSString *)path parameters:(NSDictionary *)parameters success:(void (^)(id responseObject))success failure:(void (^)(NSError *error))failure;

As stated above, we strongly suggest you use higher level methods available in the classes BAAFile, BAAObject and BAAUser and to resort to the BAAClient methods only if you can’t do otherwise. We will soon finish the implementation of the SDK so that you won’t neeed to use BAAClient methods at all in your app.

1
2
3
4
5
6
7
8
9
10
11
12
13

// Assumes there is a logged in user
BAAClient *client = [BAAClient sharedClient];
[client getPath:@"/file/details"
parameters:parameters
success:^(id responseObject) {

NSLog(@"response is %@", responseObject);

} failure:^(NSError *error) {

NSLog(@"error is %@", error);

}];

1

NOTHING HERE. See the 'iOS' Tab

1

NOTHING HERE. See the 'iOS' Tab

1

NOTHING HERE. See the 'iOS' Tab

Android SDK

BaasBox provides a native Android SDK, to further ease development of mobile applications. The SDK is distributed as a jar. To get started download it from the download section of the website, and put it in the libs folder of your project. You can also use maven gradle or maven to depend on the library:

compile 'com.baasbox:baasbox-android:0.9.0'

Initialization

Currently, you can have only one client per application. The client must be initialized before you can use any of the provided features. The preferred way to initialize the SDK is to override the default application and configure it in the onCreate() method, using the BaasBox.Builder class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

//...
import com.baasbox.android.BaasBox;

public class MyApp extends Application {

private BaasBox client;

@Override
public void onCreate() {
super.onCreate();
BaasBox.Builder b =
new BaasBox.Builder(this);
client = b.setApiDomain("address")
.setAppCode("appcode")
.setPushSenderIds("your google sender id") //used for push notifications
.init();
}
}

1

NOTHING HERE. See the 'Android' Tab

1

NOTHING HERE. See the 'Android' Tab

1

NOTHING HERE. See the 'Android' Tab

General usage

Most BaasBox REST resources are exposed through wrapper classes. Endpoints are accessible through asynchronous methods, that accept a general callback interface BaasHandler<T>

You can also access endpoints using synchronous alternatives using the *Sync version of the methods.

Results are always wrapped in BaasResult<T>, this can represent the actual result or a failure.

You can control asynchronous requests through the returned RequestToken.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Here  BaasDocument is used as an example
// it represents documents on the server, 
// more on this later

// asynchronous request
RequestToken tok = BaasDocument.fetchAll("coll",
new BaasHandler<List<BaasDocument>>() {
@Override
public void handle(BaasResult<List<BaasDocument>> res) {
// res is the result of the request
}
});

// synchronous equivalent BLOCKS!!!
BaasResult<List<BaasDocument>> res =
BaasDocument.fetchAllSync("coll");

1

NOTHING HERE. See the 'Android' Tab

1

NOTHING HERE. See the 'Android' Tab

1

NOTHING HERE. See the 'Android' Tab

Asynchronous requests management

Asynchronous requests are executed by a pool of threads. While an asynchronous request is running you can manage it using the return value of the method, a RequestToken. Tokens are designed to let you suspend the assigned callback without interrupting the real request, allowing the later resumption of result processing on the main thread when you are ready to handle it. This is quite useful when callbacks are tied to the lifecycle of your acitivities.

Request tokens let you cancel/abort requests, or wait for their completion, this is useful in testing or if you want to parallelize your http requests.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// an example asynchronous request in an activity
public class MyActivity extends Activity implements
BaasHandler<BaasUser>{
private final statis String BAAS_REQ = "tag";
private RequestToken token;

public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// you resume suspended requests
// and obtain the token back
token = RequestToken.loadAndResume(
savedInstanceState,
BAAS_REQ,
this);
if(token!=null){
// a request has been resumed
}
}

public void onSaveInstanceSate(Bundle state){
super.onSaveInstanceState(state);
if(token!=null){
token.suspendAndSave(state,TAG);
}
}

public void handle(BaasResult<BaasUser> res){
token = null;
// process result
}
}

1

NOTHING HERE. See the 'Android' Tab

1

NOTHING HERE. See the 'Android' Tab

1

NOTHING HERE. See the 'Android' Tab

Pass-through API

Some rest endpoints have no direct equivalent in the API. For them you can use the lower level pass through API provided by the SDK through the rest() and restSync() methods. Whenever you see “TO BE IMPLEMENTED” in the Android section you can recur to this methods. Using these methods you can access these APIs while still enjoying the rest of the SDK features, such as concurrency and lifecycle management, caching, handling of the authentication.

1
2
3
4
5
6
7
8
9

BaasBox cli  = BaasBox.getDefault();
cli.rest(HttpRequest.GET,
"endpoint",
optJsonBody,
authenticate,
new BaasHandler<JsonObject>(){
@Override
public void handle(BaasResult<JsonObject> res){
}});

1

NOTHING HERE. See the 'Android' Tab

1

NOTHING HERE. See the 'Android' Tab

1

NOTHING HERE. See the 'Android' Tab

JavaScript SDK

The JavaScript SDK is based on jQuery. The example page contains an example of each API call available.

Importing

You can download the SDK from the download page. To use the SDK just import jQuery and the baasbox.js in the head section of your page like this.

1

NOTHING HERE. See the 'Javascript' Tab

1

NOTHING HERE. See the 'Javascript' Tab

1

NOTHING HERE. See the 'Javascript' Tab

1
2
3
4
5
6
7
8
9
10
11
12

<script src="http://code.jquery.com/jquery-1.9.1.min.js"></script> 
<script src="baasbox.js"></script>
<script type="text/javascript" charset="utf-8">

    $(document).ready(function() {
        BaasBox.setEndPoint("http://localhost:9000"); //the address of your BaasBox server
        BaasBox.appcode = "1234567890";               //the application code of your server
        ...
        ...
        ...
    };

The jQuery cookie plugin, which you need to save authentication tokens, is already included at the top of the baasbox.js file. The SDK also supports Zepto.

Pass-through API

For any non-implemented API you can use the jQuery $.ajax interface.

API

General Remarks

These are the general notes about the REST API protocol used by BaasBox and its JSON format.

The response

Every response generated by BaasBox as a result of a REST call is a JSON object. In case of error, the data returned are more detailed and are useful to understand why the request was rejected.

Baasbox adds a “Date” header to every response reporting the date/time info, formatted using the RFC 1123 specification.

1
2
3
4
5

{
  "result": "ok|ko",
  "http_code": (200|201|204),
  "data": {  }
}

1
2
3
4
5
6
7
8
9

{
    "result": "error",
    "bb_code": <custom error code, if necessary>,
    "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..."
}

Custom error codes

These are custom error codes specific to BaasBox, returned into the bb_code field.

• 40001: You are attempting to update a database object with older data. Version is not the same.
• 40002: The ACL field is not a valid JSON string.
• 40003: The specified permission is unknown. Valid ones are ‘read’, 'update’, 'delete’, 'all’.
• 40004: Only users and roles can be used.
• 40005: The specified user does not exist.
• 40006: The specified role does not exist.
• 40010: The JSON value must be an array.
• 40011: The body payload cannot be empty.
• 40101: Authentication info not valid or not provided. HINT: has your session expired?.
• 40020: The body payload doesn’t contain the 'message’ key or message value is NOT a String.
• 40021: Push profile invalid. It must be an Array of integer and accepted values are 1,2 or 3.
• 40022: Users MUST be an array of String.
• 40023: The body payload doesn’t contain key users.
• 40024: Sound value MUST be a String.
• 40025: Badge value MUST be a number.
• 40026: ActionLocalizedKey MUST be a String
• 40027: LocalizedKey MUST be a String.
• 40028: LocalizedArguments MUST be an Array of String.
• 40029: Collapse_key MUST be a String
• 40030: Time_to_live MUST be a positive number or equal zero.
• 40031: Message MUST be a String.
• 50301: Push settings are not properly configured. HINT: go to the 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).
  
• 50304: Could not save API KEY. HINT: Check your API Key, it’s possible that push service aren’t enabled in the Google Play Developer Console.
• 50305: Push app disabled, one or more app are disabled.
  
• 50306: Cannot switch, because settings for the selected mode are missing.

Pagination and query criteria

Some queries support pagination. There are two important parameters in paginated calls.

Example of valid calls:

• /document/mycollection/count?where=color%3D’yellow’
• /document/mycollection/count?where=color%3D%3F&params%3dyellow
• /document/documents/count?where=color%3D%3F%20or%20color%3D%3F&params=yellow&params=cyan

1
2
3

curl 'http://localhost:9000/users?page=0&recordsPerPage=1' \
     -H X-BB-SESSION:f083f676-65d0-45bd-bfe5-e876ef3f659e

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

NSDictionary *parameters =
  @{kPageNumberKey : @0,
    kPageSizeKey : [NSNumber numberWithInteger:kPageLength]};
[BAAUser loadUsersWithParameters:parameters
                      completion:^(NSArray *users, NSError *e) {
                          if (error == nil) {
                            NSLog(@"users are %@", users);
                          } else {
                            // deal with error
                          }
                      }];

// Apply a filter using the where keyword
NSDictionary *parameters = @{@"where" : "color='red'"};
[Post getObjectsWithParams:parameters
                completion:^(NSArray *posts, NSError *error) {
                    if (error == nil) {
                        NSLog(@"Posts are %@", posts);
                    } else {
                        // deal with error
                    }
                }];

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

Criteria paginate = BaasQuery.builder()
                           .pagination(0,30)
                           .orderBy("user.name")
                           .criteria();

BaasUser.fetchAll(paginate,new BaasHandler<List<BaasUser>>() {
  @Override
  public void handle(BaasResult<List<BaasUser>> res) {
    if (res.isSuccess()) {
      for(BaasUser user:res.value()) {
        Log.d("LOG","User is: "+user);
      }
    } else {
      Log.e("LOG","error",res.error());
    }
  }
});

// aggregate operations and complex queries
private static final BaasQuery PREPARED_QUERY =
   BaasQuery.builder()
            .collection("collection")
            .projection("field","aggreateOp")
            .where("condition")
            .whereParams("positionalParam","positionalParam2")
            .groupBy("field")
            .orderBy("field asc")
            .pagination(2,20)
            .build();
// then
PREPARED_QUERY.query(new BaasHandler<List<JsonObject>>(){
  @Override
  public void handle(BaasResult<List<JsonObjec>> res){
    // handle result or failure
  }
});

1

NOTHING HERE

User Management

Sign up

POST /user

Group: baasbox.account.create

Headers: See authorization header in the General Remarks

Description: This API allows a user to sign up to the App. Users will belong to the registered user role and they will post new content, will retrieve their own content, will change their password. BaasBox, since v.0.9.4, assigns a unique ID to each user. This ID can be used with the Link API.

You can force your own ID only via plugin script.

Please see the Plugin Users API documentation

1
2
3
4

curl http://localhost:9000/user \
    -d '{"username" : "cesare", "password" : "password"}' \
    -H Content-type:application/json \
    -H X-BAASBOX-APPCODE:1234567890

1
2
3
4
5
6
7
8
9
10
11
12

BAAClient *client = [BAAClient sharedClient];
[client createUserWithUsername:@"cesare"
                      password:@"password"
                    completion:^(BOOL success, NSError *error) {

                          if (success) {
                              NSLog(@"user is %@", client.currentUser);
                          } else {
                              // display error
                          }

 }];

1
2
3
4
5
6
7
8
9
10
11
12
13
14

BaasUser user = BaasUser.withUserName("andrea");
                        .setPassword("password");
JsonObject extras = user.getScope(Scope.PRIVATE)
                        .putInt("age_info",27);
user.signup(new BaasHandler<BaasUser>(){
  @Override
  public void handle(BaasResult<BaasUser> result){
    if(result.isSuccess()) {
      Log.d("LOG","Current user is: "+result.value());
    } else {
      Log.e("LOG","Show error",result.error());
    }
  }
});

1
2
3
4
5
6
7

BaasBox.signup("cesare", "password")
    .done(function (res) {
    console.log("signup ", res);
  })
  .fail(function (error) {
    console.log("error ", error);
  })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "result": "ok",
  "data": {
    "user": {
      "name": "cesare",
      "status": "ACTIVE",
      "roles": [{"name": "registered"}]
    },
    "id": "6d5d8300-4339-40a5-8688-d1547fec6e05",
    "visibleByAnonymousUsers": { },
    "visibleByTheUser": { },
    "visibleByFriends": { },
    "visibleByRegisteredUsers": {
        "_social": { }
    },
    "signUpDate": "2015-06-16T16:20:32.032+0200",
    "generated_username": false,
    "X-BB-SESSION": "7f943d99-5872-4f0e-9865-a02386ef882b"
  },
  "http_code": 201
}

Here is the explanantion of the server response:

Login

POST /login

Group: baasbox.account

Checks username/password and grants the user the right to execute other calls. This API returns a session token (X-BB-SESSION) that must be provided into all authenticated calls.

This API supports both application/x-www-form-urlencoded and application/json content types.

1
2
3
4

curl http://localhost:9000/login \
    -d "username=cesare" \
    -d "password=password" \
    -d "appcode=1234567890"

1
2
3
4
5
6
7
8
9

[BAAUser loginWithUsername:@"cesare"
                  password:@"password"
                completion:^(BOOL success, NSError *error) {
                  if (success) {
                    NSLog(@"user is %@", client.currentUser);
                  } else {
                    // show error
                  }
                }];

1
2
3
4
5
6
7
8
9
10
11
12

BaasUser user = BaasUser.withUserName("andrea")
                        .setPassword("password");
user.login(new BaasHandler<BaasUser>() {
  @Override
  public void handle(BaasResult<BaasUser> result) {
    if(result.isSucces()) {
      Log.d("LOG", "The user is currently logged in: "+result.value());
    } else {
      Log.e("LOG","Show error",result.error());
    }
  }
});

1
2
3
4
5
6
7

BaasBox.login("cesare", "password")
    .done(function (user) {
        console.log("Logged in ", user);
    })
    .fail(function (err) {
        console.log("error ", err);
    })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
    "result": "ok",
    "data": {
        "user": {
            "name": "cesare",
            "status": "ACTIVE",
            "roles": [{"name": "registered"}]
        },
        "id": "6d5d8300-4339-40a5-8688-d1547fec6e05",
        "visibleByAnonymousUsers": { },
        "visibleByTheUser": { },
        "visibleByFriends": { },
        "visibleByRegisteredUsers": {
            "_social": { }
        },
        "signUpDate": "2015-06-16T16:20:32.032+0200",
        "generated_username": false,
        "X-BB-SESSION": "7f943d99-5872-4f0e-9865-a02386ef882b"
    },
    "http_code": 201
}

Here is the explanantion of the server response:

Logout

POST /logout[/:pushToken]

Group: baasbox.account

Allows a user to logout from the app on a specific device. A push notification will not be sent to the user through the specified device.

1
2

curl -X POST http://localhost:9000/logout \
    -H X-BB-SESSION:da506029-4512-45a9-9606-43fcdda4121a -H X-BAASBOX-APPCODE:1234567890

1
2
3
4
5
6
7
8
9

[BAAUser logoutWithCompletion:^(BOOL success, NSError *error) {

    if (success) {
        // user logged out
    } else {
        // error logging out
    }

}];

1
2
3
4
5
6
7
8
9
10

BaasUser.current().logout(new BaasHandler<Void>() {
  @Override
  public void handle(BaasResult<Void> result) {
    if(result.isSuccess()) {
      Log.d("LOG", "Logged out: "+(BaasUser.current() == null));
    } else{
      Log.e("LOG","Show error",result.error());
    }
  };
});

1
2
3
4
5
6
7

BaasBox.logout()
  .done(function (res) {
    console.log(res);
  })
  .fail(function (error) {
    console.log("error ", error);
  })

1
2
3
4
5

{
 "result":"ok",
 "data":"user logged out",
 "http_code":200
}

Suspend a user

Suspends a given user.

Only administrators can call this API.

PUT /me/suspend

1
2
3

curl -X PUT http://localhost:9000/me/suspend \
    -H X-BB-SESSION:da506029-4512-45a9-9606-43fcdda4341a \
    -H X-BAASBOX-APPCODE:1234567890

Allows a user to suspend their account.

Only administators can reactivate it.

PUT /admin/user/suspend/:username

1
2
3

curl -X PUT http://localhost:9000/admin/user/suspend/user1 \
    -H X-BB-SESSION:da506029-4512-45a9-9606-43fcdda4121a \
    -H X-BAASBOX-APPCODE:1234567890

Reactivate a user

PUT /admin/user/activate/:username

1
2
3

curl -X PUT http://localhost:9000/admin/user/activate/user1 \
    -H X-BB-SESSION:da506029-4512-45a9-9606-43fcdda4121a \
    -H X-BAASBOX-APPCODE:1234567890

Reactivate a previoulsy suspended user.

Only administrators can call this API.

Logged user profile

GET /me

Group: baasbox.account

Retrieves details about the logged in user.

1
2

curl http://localhost:9000/me \
    -H X-BB-SESSION:196f48ed-6154-4b49-8dc6-8b9b2ce4900a

1
2
3
4
5
6
7
8
9

[BAAUser loadCurrentUserWithCompletion:^(BAAUser *user, NSError *error) {

    if (error == nil) {
        // deal with user object
    } else {
        // deal with error
    }

}];

1
2
3
4
5
6
7
8
9
10
11
12

BaasUser.current().refresh(new BaasHandler<BaasUser>() {
  @Override
  public void handle(BaasResult<BaasUser> result) {
    if(result.isSuccess()) {
      BaasUser user = result.value();
      JsonObject data = user.getScope(Scope.PRIVATE);
      Log.d("LOG","Log some private data: "+data);
    } else {
      Log.e("LOG","error:",result.error());
    }
  }
});

1
2
3
4
5
6
7

BaasBox.fetchCurrentUser()
  .done(function(res) {
    console.log("res ", res['data']);
  })
  .fail(function(error) {
    console.log("error ", error);
  })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
"result": "ok",
    "data": {
        "user": {
            "name": "cesare",
            "status": "ACTIVE",
            "roles": [{"name": "registered"}]
        },
        "id": "6d5d8300-4339-40a5-8688-d1547fec6e05",
        "visibleByAnonymousUsers": { },
        "visibleByTheUser": { },
        "visibleByFriends": { },
        "visibleByRegisteredUsers": {
            "_social": { }
        },
        "signUpDate": "2015-06-16T16:20:32.032+0200",
        "generated_username": false,
        "X-BB-SESSION": "7f943d99-5872-4f0e-9865-a02386ef882b"
        },
    "http_code": 201
}

Update user profile

PUT /me

Group: baasbox.account

Updates details about the logged in user.

The body payload to be sent has the following form:

{ "visibleByTheUser": {}, "visibleByFriends": {}, "visibleByRegisteredUsers": {}, "visibleByAnonymousUsers": {} }

All four properties are optional. You can send just one of them or all four. See example on the right. The values for this fields can be anything you like: string, numbers, arrays or JSON encoded objects.

1
2
3
4

curl -X PUT http://localhost:9000/me \
    -d '{"visibleByFriends" : {"phoneNumber" : "+1123456"}}' \
    -H Content-type:application/json \
    -H X-BB-SESSION:a30e8f43-4d90-4324-91d2-6065fa6ca63c

1
2
3
4
5
6
7
8
9
10
11

BAAUser *user = ... ; // some user
[user.visibleByAnonymousUsers setObject:@"mail@mail.com" forKey:@"email"];
[user updateWithCompletion:^(BAAUser *user, NSError *error) {

    if (error == nil) {
        NSLog(@"user is %@", [user jsonString]);
    } else {
        NSLog(@"error %@", error);
    }

}];

1
2
3
4
5
6
7
8
9
10
11
12

BaasUser user = BaasUser.current();
user.getScope(Scope.PRIVATE).putString("property","value");
user.save(new BaasHandler<BaasUser>() {
  @Override
  public void handle(BaasResult<BaasUser> res) {
    if(res.isSuccess()) {
      Log.d("LOG", "User data has been saved");
    } else {
      Log.e("LOG", error,res.error());
    }
  }
});

1
2
3
4
5
6
7

BaasBox.updateUserProfile({"visibleByAnonymousUsers": {"email" : "mail@mail.com"}})
  .done(function(res) {
    console.log("res ", res['data']);
  })
  .fail(function(error) {
    console.log("error ", error);
  })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "result": "ok",
  "data": {
    "user": {
      "name": "cesare",
      "status": "ACTIVE",
      "roles": [
        {
          "name": "registered"
        }
      ]
    },
    "signUpDate": "2014-01-24T11:28:09.009+0100",
    "visibleByFriends": {
      "phoneNumber": "+1123456"
    }
  },
  "http_code": 200
}

Fetch a user profile

GET /user/:username

Group: baasbox.users

Allows to retrieve information about a user profile.

1
2

curl http://localhost:9000/user/cesare \
     -H X-BB-SESSION:f083f676-65d0-45bd-bfe5-e876ef3f659e

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[BAAUser loadUserDetails:@"cesare"
              completion:^(BAAUser *user, NSError *error) {

    if (error == nil) {

        NSLog(@"user details are %@", user);

    } else {

        // deal with error

    }

}];

1
2
3
4
5
6
7
8
9
10
11

BaasUser.fetch("a",new BaasHandler<BaasUser>() {
  @Override
  public void handle(BaasResult<BaasUser> res) {
    if(res.isSuccess()){
      BaasUser user = res.value();
      Log.d("LOG","The user: "+user);
    } else {
      Log.e("LOG","Error",res.error());
    }
  }
});

1
2
3
4
5
6
7

BaasBox.fetchUserProfile("cesare")
  .done(function(res) {
    console.log("res ", res['data']);
  })
  .fail(function(error) {
    console.log("error ", error);
  })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "result": "ok",
  "data": {
    "user": {
      "name": "a",
      "status": "ACTIVE",
      "visibleByFriends": {"phoneNumber":"+1985478562"}},
      "roles": [
        {
          "name": "registered"
        }
      ]
    },
    "signUpDate": "2014-01-24T12:13:08.008+0100"
  }

Fetch users

GET /users

Group: baasbox.users

Allows to retrieve a list of users. This API supports pagination and query criteria.

1
2

curl http://localhost:9000/users \
     -H X-BB-SESSION:f083f676-65d0-45bd-bfe5-e876ef3f659e

1
2
3
4
5
6
7
8
9
10
11
12

NSDictionary *parameters = @{kPageNumberKey : @0,
                             kPageSizeKey : [NSNumber numberWithInteger:kPageLength]};
[BAAUser loadUsersWithParameters:parameters
                      completion:^(NSArray *users, NSError *error) {

                          if (error == nil) {
                            NSLog(@"users are %@", users);
                          } else {
                            // deal with error
                          }

                      }];

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Criteria filter = BaasQuery.builder()
                         .pagination(0,2)
                         .orderBy("user.name")
                         .criteria();
BaasUser.fetchAll(filter,new BaasHandler<List<BaasUser>>() {
  @Override
  public void handle(BaasResult<List<BaasUser>> res) {
    if(res.isSuccess()) {
      for(BaasUser u: res.value()) {
        Log.d("LOG", "The user is: "+u.getName());
      }
    } else {
      Log.e("LOG","error");
    }
  }
});

1
2
3
4
5
6
7

BaasBox.fetchUsers()
  .done(function(res) {
    console.log("res ", res['data']);
  })
  .fail(function(error) {
    console.log("error ", error);
  })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  "result": "ok",
  "data": [
    {
      "user": {
        "roles": [
          {
            "name": "registered"
          }
        ],
        "name": "cesare",
        "status": "ACTIVE"
      },
      "signUpDate": "2014-01-24T11:28:09.009+0100",
      "visibleByTheUser": {
        "email": "cesare@email.com"
      },
      "visibleByFriends": {
        "phoneNumber": "+1123456"
      }
    },
    {
      "user": {
        "roles": [
          {
            "name": "registered"
          }
        ],
        "name": "e",
        "status": "ACTIVE"
      },
      "signUpDate": "2014-01-24T12:10:37.037+0100"
    }
  ],
  "http_code": 200
}

Change password

PUT /me/password

Group: baasbox.account

To change the password of the logged in user.

1
2
3
4

curl -X PUT http://localhost:9000/me/password \
-d '{"old" : "oldpass", "new" : "newpass"}' \
-H Content-type:application/json \
-H X-BB-SESSION:a30e8f43-4d90-4324-91d2-6065fa6ca63c

1
2
3
4
5
6
7
8
9
10
11
12

BAAUser *user = ...; // Some user
[user changeOldPassword:@"oldpass"
toNewPassword:@"newpass"
completionBlock:^(BOOL success, NSError *error) {

if (success) {
NSLog(@"pass updared");
} else {
NSLog(@"err %@", error);
}

}];

1
2
3
4
5
6
7
8
9
10

BaasUser current = BaasUser.current();
current.changePassword("newpassword",new BaasHandler<Void>() {
public Void handle(BaasHandler<Void> res) {
if(res.isSuccess()) {
Log.d("LOG", "New password updated, you should relogin");
} else {
Log.e("LOG","error",res.error());
}
}
});

1
2
3
4
5
6
7

BaasBox.changePassword("oldpass", "newpass")
.done(function(res) {
console.log("res ", res);
})
.fail(function(error) {
console.log("error ", error);
})

1
2
3
4
5

{
"result": "ok",
"data": "",
"http_code": 200
}

Change username

PUT /me/username

Group: baasbox.users

Headers: See authorization header in the General Remarks

Description: Starting from v. 0.9.0 it is possibile to change usernames

1
2
3
4

curl -X PUT  http://localhost:9000/me/username  \
-d '{"username" : "matteo"}' \
-H Content-type:application/json \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2

//Please see the "pass-through" functionality of the iOS SDK

1
2

//Please see the "pass-through" functionality of the Android SDK

1
2

//Please see the "pass-through" functionality of the JS SDK

1
2
3
4
5
6

{
"result": "ok",
"data": "",
"http_code": 200
}

Password reset

(Forgotten password workflow)

GET /user/:username/password/reset

Group: baasbox.account.lost_password

Allows to reset a user’s password. This API is useful when users forget their password and need to reset it. This is the workflow:

• the server checks if the email address exists within the visibleByTheUser fields in the user profile
• the server sends an email to that address with a generated link to follow in order to reset the password
• the user opens the email and opens the given link in a web browser. That will show a form with two html password fields
• the user fills in the two fields and submits the form
• a confirmation message is shown by the server
• the settings (SMTP configuration, email message to be sent, html form, confirmation and error web page) can be set up by the administrator via the Settings menu in the admin console

1
2

curl http://localhost:9000/user/cesare/password/reset \
-H X-BAASBOX-APPCODE:1234567890

1
2
3
4
5
6
7
8
9
10

BAAUser *user = ... ; // Some user
[user resetPasswordWithCompletion:^(BOOL success, NSError *error) {

if (success) {
NSLog(@"password reset OK");
} else {
NSLog(@"error %@", error);
}

}];

1
2
3
4
5
6
7
8
9
10

BaasUser.requestPasswordReset("cesare",new BaasHandler<Void>() {
@Override
public void handle(BaasResult<Void> res) {
if(res.isSuccess()) {
Log.d("LOG","Password reset has been requested");
} else{
Log.e("LOG","Error",res.error());
}
}
};

1
2
3
4
5
6
7

BaasBox.resetPassword()
.done(function(res) {
console.log("res ", res);
})
.fail(function(error) {
console.log("error ", error);
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
"result": "error",
"message": "Cannot reset password, the \"email\" attribute is not defined into the user's private profile",
"resource": "/user/cesare/password/reset",
"method": "GET",
"request_header": {
"Accept": [
"*/*"
],
"Host": [
"localhost:9000"
],
"X-BAASBOX-APPCODE": [
"1234567890"
]
},
"API_version": "<BaasBox version>"
}

Social Login

BaasBox provides an API that allows you to connect/create your users through social networks.

BaasBox social API is integrated with the following social networks: - Facebook - Google +

We are planning on adding more in the near future.

The use of an API in a client application needs an appKey and an appSecret usually provided by the social network itself. More information on how you can get those values can be found here:

• facebook (http://developers.facebook.com/docs/)
• google+ (http://code.google.com/apis/console)

Once you create your app inside the social network you will have access to the apiKey / apiSecret values; those values must be stored into the BaasBox database in order to use the BaasBox social feature: you can access the social login tab from the settings menu in the admin console.

Then click on the specific social network you are working on, fill in the form with the keys and press Save. You can disable the social feature for a specific social network by pressing the disable xxx button

Once you have connected to a social network you can use any client library to obtain the OAuth tokens for users account, and store them with the social API provided by BaasBox.

You can find an application example and tutorial here

API documentation

Retrieve all social network connections for a connected user

GET /social

Headers:

• X-BAASBOX-APPCODE: App Code
• X-BB-SESSION: Session token for current user

Returns a JSON representation of the social network connected to the user along with all the information retrieved at the moment of login/linking. An example of the returned data is:

1
2

curl http://localhost:9000/social  \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Assumes a user is logged in
BAAClient *client = [BAAClient sharedClient];
[client.currentUser fetchLinkedSocialNetworksWithCompletion:^(NSArray *objects, NSError *error) {

if (error == nil) {

NSLog(@"social are %@", objects);

} else {

NSLog(@"%@", error);

}

}];

1

TO BE IMPLEMENTED

1

TO BE IMPLEMENTED

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

"data": [
{
"username": "xxx",
"password": null,
"from": "google",
"token": "<token>",
"secret": "<secret>",
"id": "<userid>",
"additionalData": {
"email": "<email>",
"name": "<name>",
"avatarUrl": "<avatar>",
"personal_url": "<personal_url>"
}
}
]

This API should be invoked with a valid X-BB-SESSION header and a valid X-BAASBOX-APPCODE header as specified in the authorization section of the doc.

This method can be used to retrieve the tokens to post on the social network wall using a client SDK provided by the social network itself.

Returns:

• 200 code with a JSON object whose data property contains all the social networks linked to the current user.
• 404 code if the user does not have any social network linked to their account
• 401 code (Unauthorized) if one of the mandatory headers are missing

Login a User with a specified social network

POST /social/:socialNetwork

Headers: X-BAASBOX-APPCODE = App code

URL parameters

:socialNetwork could be facebook or google

Parameters:

• oauth_token: the oauth_token obtained after user authentication and authorization with a client library (see example here)

• oauth_secret: the oauth_secret obtained after user authentication and authorization with a client library (see example here)

This method allows to login into the BaasBox app using the tokens obtained by a social network client library. If the user has already logged in with the same tokens the server will simply return the X-BB-SESSION token that will be used for further requests.

If the user does not exist it will be created and an X-BB-SESSION token will be returned. Upon user creation some data will be extracted from the social network profile and they will be stored inside the user object. A username will be uniquely generated (to prevent username collision). Therefore after a succesful login, if necessary, the client app may ask for a username and update the user object accordingly.(See the example here)

Returns:

• 200 code with the user’s X-BB-SESSION token
• 400 code if one of the oauth_token or oauth_secret was missing
• 401 code if the X-BAASBOX-APPCODE header was missing
• 500 code if something on the server went wrong (i.e. another user with the same tokens already exists)

1
2
3
4

curl -X POST  http://localhost:9000/social/facebook  \
-d "oauth_token=OAUTH_TOKEN" \
-d "oauth_secret=OAUTH_SECRET" \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

NSString *token = ... ; // Valid authentication token obtained by Facebook.
[BAAUser loginWithFacebookToken:token
completion:^(BOOL success, NSError *error) {

if (success) {

BAAClient *c = [BAAClient sharedClient];
NSLog(@"logged in with facebook %@", c.currentUser);

} else {

NSLog(@"error %@", error);

}

}];

1
2
3
4
5
6
7
8

String token= ...;// a valid token from the provider
BaasUser.signupWithProvider(Social.FACEBOOK,token,token,new BaasHandler<BaasUser>(){
@Override
public void handler(BaasResult<BaasUser> res) {
if(res.isSuccess()){
BaasUser current = res.value();
}
});

1

TO BE IMPLEMENTED

1
2
3
4

curl -X POST  http://localhost:9000/social/google  \
-d "oauth_token=OAUTH_TOKEN" \
-d "oauth_secret=OAUTH_SECRET" \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

NSString *token = ... ; // Valid authentication token obtained by Google.
[BAAUser loginWithGoogleToken:token
completion:^(BOOL success, NSError *error) {

if (success) {

BAAClient *c = [BAAClient sharedClient];
NSLog(@"logged in with facebook %@", c.currentUser);

} else {

NSLog(@"error %@", error);

}

}];

1

TO BE IMPLEMENTED

1

TO BE IMPLEMENTED

Link a user to a specified social network

PUT /social/:socialNetwork

Headers:

• X-BAASBOX-APPCODE = App code
• X-BB-SESSION = Session token for the current user

URL parameters

:socialNetwork could be facebook or google

Parameters: oauth_token: the oauth_token obtained after user authentication and authorization with a client library (see example here)

oauth_secret: the oauth_secret obtained after user authentication and authorization with a client library (see example here)

This method allows an existing user to connect their account to a specified social network.

This procedure is very similar to the Login method with a difference: this is a PUT request and it must be invoked with the X-BB-SESSION header.

Returns: - 200 code with an empty response if the linking was succesful, - 401 code if any of the mandatory headers was missing, - 500 code if something on the server went wrong (i.e. another user with the same tokens already exists)

1
2
3
4

curl -X PUT http://localhost:9000/social/facebook  \
-d "oauth_token=OAUTH_TOKEN" \
-d "oauth_secret=OAUTH_SECRET" \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11
12
13

// Assumes a user is already logged in
NSString *token = ...; // Token obtained by Facebook
BAAClient *client = [BAAClient sharedClient];
[client.currentUser linkToFacebookWithToken:token
completion:^(BOOL success, NSError *error) {

if (success) {
NSLog(@"user linked to FB");
} else {
NSLog(@"error %@", error);
}

}];

1

TO BE IMPLEMENTED

1

TO BE IMPLEMENTED

1
2
3
4

curl -X PUT http://localhost:9000/social/google  \
-d "oauth_token=OAUTH_TOKEN" \
-d "oauth_secret=OAUTH_SECRET" \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11
12
13

// Assumes a user is already logged in
NSString *token = ...; // Token obtained by Google
BAAClient *client = [BAAClient sharedClient];
[client.currentUser linkToGoogleWithToken:token
completion:^(BOOL success, NSError *error) {

if (success) {
NSLog(@"user linked to FB");
} else {
NSLog(@"error %@", error);
}

}];

1

TO BE IMPLEMENTED

1

TO BE IMPLEMENTED

Unlink a user from a specified social network

DELETE /social/:socialNetwork

Headers:

• X-BAASBOX-APPCODE = App code
• X-BB-SESSION = Session token for current user

URL parameters: socialNetwork could be facebook or google

This method unlinks the current user account from a specified social network. If the user was generated by a social network login and the specified social network is the only one linked to the user, an error will be raised (as the user will not be available to connect anymore).

1
2

curl -X DELETE http://localhost:9000/social/facebook  \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11

// Assumes a user is already logged in
BAAClient *client = [BAAClient sharedClient];
[client.currentUser unlinkFromFacebookWithCompletion:^(BOOL success, NSError *error) {

if (success) {
NSLog(@"account unlinked");
} else {
NSLog(@"error %@", error);
}

}];

1

TO BE IMPLEMENTED

1

TO BE IMPLEMENTED

1
2

curl -X DELETE http://localhost:9000/social/google  \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11

// Assumes a user is already logged in
BAAClient *client = [BAAClient sharedClient];
[client.currentUser unlinkFromGoogleWithCompletion:^(BOOL success, NSError *error) {

if (success) {
NSLog(@"account unlinked");
} else {
NSLog(@"error %@", error);
}

}];

1

TO BE IMPLEMENTED

1

TO BE IMPLEMENTED

Friendship and Social API

BaasBox is able to manage relations among users, implementing a concept of friendship similar (but not identical) to the one used by Twitter. A user registered on BaasBox can “follow” another user calling the follow API.

What happens is that such user is added to a special role called friends_of_<followed user>.

For example, let’s say we have three users: user_a, user_b, user_c. user_b and user_c decide to follow user_a, and therefore, each of them with their own credentials will call the API follow_:

PUT /follow/user_a

now user_b_ and user_c belong to the group friends_ofuser_a_.

When user_a wants to share something with his followers, he just has to grant reading access to his content to users belonging to the role friends_ofuser_a_.

For example, supposing that there is a defined collection called posts, and that user_a had created in it a document with id aaa-bbb-ccc-ddd.

user_a in order to share this document with his friends has to call the grant API:

PUT /document/posts/aaa-bbb-ccc-ddd/read/role/friends_of_user_a

Now everytime user_b or user_c query for posts they will see the _user_a aaa-bbb-ccc-ddd document as well.

To revoke such grant, and therefore not to share the content any longer:

DELETE /document/posts/aaa-bbb-ccc-ddd/read/role/friends_of_user_a

Finally, if user_b doesn’t want to follow user_a anymore, he can invoke the unfollow API:

DELETE /follow/user_a

Please note that the follow API is not mutual, just like in Twitter.

Follow a user

POST /follow/:username

Group: baasbox.friendship.create

This API allows a user to follow another user. Once the relation is established the follower will be able to see the documents and files created by the followed user as well as its visibleByFriends data in the user profile.

1
2

curl -X POST http://localhost:9000/follow/cesare \
     -H X-BB-SESSION:c6fb7001-ccb5-4048-8935-80ef197e1390

1
2
3
4
5
6
7
8
9
10
11
12

BAAUser *user = ...; // Instance of user to be followed

[BAAUser followUser:user
         completion:^(BAAUser *user, NSError *error) {

             if (error == nil) {
                 NSLog(@"now following user %@", user);
             } else {
                 // deal with error
             }

         }];

1
2
3
4
5
6
7
8
9
10
11
12
13

BaasUser user = BaasUser.withUsername("cesare");
user.follow(new BaasHandler<BaasUser>() {

  @Override
  public void handle(BaasResult<BaasUser> res) {
    if(res.isSuccess()) {
     JsonObject profile = res.value().getScope(Scope.FRIEND);
     Log.d("LOG", "It's profile "+profile);
    } else{
      // there was an error
    }
  }
});

1
2
3
4
5
6
7

BaasBox.followUser("cesare")
  .done(function(res) {
    console.log("res ", res['data']);
  })
  .fail(function(error) {
    console.log("error ", error);
  })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "result": "ok",
  "data": {
    "user": {
      "name": "cesare",
      "roles": [
        {
          "name": "registered"
        },
        {
          "name": "friends_of_cesare"
        }
      ],
      "status": "ACTIVE"
    },
    "signUpDate": "2014-01-24T11:28:09.009+0100",
    "visibleByFriends": {
      "phoneNumber": "+1123456"
    }
  },
  "http_code": 201
}

Unfollow a user

DELETE /follow/:username

Group: baasbox.friendship.create

This API allows a user to unfollow another user. Once the relation has been deleted, the user won’t be able to see the documents and files created by the unfollowed user anymore.

1
2

curl -X DELETE http://localhost:9000/follow/cesare \
     -H X-BB-SESSION:c6fb7001-ccb5-4048-8935-80ef197e1390

1
2
3
4
5
6
7
8
9
10
11
12

BAAUser *user = ...; // Instance of user to be unfollowed

[BAAUser unfollowUser:user
           completion:^(BAAUser *user, NSError *error) {

                 if (error == nil) {
                     NSLog(@"not following anymore user %@", user);
                 } else {
                     // deal with error
                 }

         }];

1
2
3
4
5
6
7
8
9
10
11
12

BaasUser.withUserName("cesare").unfollow(
  new BaasHandler<BaasUser>() {
    @Override
    public void handle(BaasResult<BaasUser> res) {
      if(res.isSuccess()) {
        JsonObject data = res.value().getScope(Scope.FRIEND);
        Log.d("LOG", "No more friend data:"+(data==null));
      } else {
        // there was an error
      }
    }
  });

1
2
3
4
5
6
7

BaasBox.unfollowUser("cesare")
  .done(function(res) {
    console.log("res ", res);
  })
  .fail(function(error) {
    console.log("error ", error);
  })

1
2
3
4
5

{
  "result": "ok",
  "data": "",
  "http_code": 200
}

Fetch following

GET /following/:username

Group: baasbox.friendship

This API returns a list of users who are followed by the user with username passed as a parameter. If no username is provided, the API returns all users followed by the logged in user. In its data property the method returns an array filled with the user profiles representing their “friends”. Each profile will contain the visibleByFriends data which would otherwise be hidden.

1
2

curl http://localhost:9000/following/cesare \
     -H X-BB-SESSION:c6fb7001-ccb5-4048-8935-80ef197e1390

1
2
3
4
5
6
7
8
9

BAAUser *user = ... // user representing "cesare"

[user loadFollowingWithCompletion:^(NSArray *following, NSError *error) {

            for (BAAUser *u in following) {
                NSLog("cesare is following %@", u)
            }

        }];

1
2
3
4
5
6
7
8
9
10
11
12

BaasUser user = ... // the user representing "cesare"

user.following(new BaasHandler<List<BaasUser>>() {
  @Override
  public void handle(BaasResult<List<BaasUser>> res) {
    if(res.isSuccess()){
      for(BaasUser u: res.value()) {
        Log.d("LOG","Cesare is follwing: "+u.getName());
      }
    }
  }
});

1
2
3
4
5
6
7

BaasBox.fetchFollowing("cesare")
  .done(function(res) {
    console.log("res ", res['data']);
  })
  .fail(function(error) {
    console.log("error ", error);
  })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "result": "ok",
  "data": [
    {
      "user": {
        "roles": [
          {
            "name": "registered"
          }
        ],
        "name": "a",
        "status": "ACTIVE"
      },
      "signUpDate": "2014-01-24T12:13:08.008+0100"
    }
  ],
  "http_code": 200
}

Fetch followers

GET /followers/:username

Group: baasbox.friendship

This API returns the list of followers for the user with username specified in the parameter. If no username is provided the API returns the list of followers for the currently logged in user. The method returns in its data property an array filled with the user profiles representing their “friends”. Each profile will contain the visibleByFriends data which would otherwise be protected.

1
2

curl http://localhost:9000/followers/cesare \
     -H X-BB-SESSION:c6fb7001-ccb5-4048-8935-80ef197e1390

1
2
3
4
5
6
7
8
9

BAAUser *user = ... // user representing "cesare"

[user loadFollowersWithCompletion:^(NSArray *following, NSError *error) {

            for (BAAUser *u in following) {
                NSLog("%@ is following cesare", u)
            }

        }];

1
2
3
4
5
6
7
8
9
10
11
12

BaasUser user = ... // the user representing "cesare"

user.followers(new BaasHandler<List<BaasUser>>() {
  @Override
  public void handle(BaasResult<List<BaasUser>> res) {
    if(res.isSuccess()){
      for(BaasUser u: res.value()) {
        Log.d("LOG", u.getName()+ " is following cesare");
      }
    }
  }
});

1
2
3
4
5
6
7

BaasBox.fetchFollowers("cesare")
  .done(function(res) {
    console.log("res ", res['data']);
  })
  .fail(function(error) {
    console.log("error ", error);
  })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "result": "ok",
  "data": [
    {
      "user": {
        "roles": [
          {
            "name": "registered"
          }
        ],
        "name": "a",
        "status": "ACTIVE"
      },
      "signUpDate": "2014-01-24T12:13:08.008+0100"
    }
  ],
  "http_code": 200
}

Push Notifications

Push notifications are messages that a user can receive using an APP that has BaasBox as back-end. Supported platforms are Android and iOS. Certificates have to be configured in the Settings of the console.

Enable push notifications

PUT /push/enable/:os/:pushToken

Group: baasbox.notifications.receive

Enables a specific user (logged using a specific device) to receive push notifications.

1
2

curl -X PUT  http://localhost:9000/push/enable/ios/123  \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// Call this method only AFTER a successful login or signup.
BAAClient *client = [BAAClient sharedClient];
[client askToEnablePushNotifications];

// implement these delegate methods in the app delegate.
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

    BAAClient *client = [BAAClient sharedClient];
    [client enablePushNotifications:deviceToken completion:^(BOOL success, NSError *error) {
        if (error) {
            // handle the error
        }
    }];
}

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    // handle the error
}

1
2
3
4
5
6
7
8
9
10
11

// given you have provided one or more sender ids to the initial configuration
BaasCloudMessagingService box=BaasBox.messagingService();
box.enable(new BaasHandler<Void>() {
@Override
public void handle(BaasResult<Void> res){
if(res.isSuccess()){
// registrationid saved on the server
}
}
});

1

TO BE IMPLEMENTED

1
2
3
4
5

{
"result": "ok",
"data": "",
"http_code": 200
}

Disable push notifications

PUT /push/disable/:pushToken

Group: baasbox.notifications.receive

Disable a specific user (logged using a specific device) to unreceive push notifications.

1
2

curl -X PUT  http://localhost:9000/push/disable/123  \
-H X-BB-SESSION:2605d809-03f0-4751-8f8e-5f658e179a23

1
2
3
4
5
6
7
8
9
10
11

// Assumes there is a logged in user
BAAClient *client = [BAAClient sharedClient];
[client disablePushNotificationsWithCompletion:^(BOOL success, NSError *error) {

if (success) {
NSLog(@"push notifications disabled");
} else {
NSLog(@"error %@", error);
}

}];

1
2
3
4
5
6
7
8
9

BaasCloudMessagingService client = BaasBox.messagingService();
client.disable(new BaasHandler<Void>(){
@Override
public void handle(BaasResult<Void> res){
if(res.isSuccess()){
// successfully unregistered
}
}
});

1

TO BE IMPLEMENTED

1
2
3
4
5

{
"result": "ok",
"data": "",
"http_code": 200
}

Send a push notification

For information about additional data check the following links

• iOS
• Android

POST /push/message/

Group: baasbox.notifications.send

Allows to send a push notification. This will be sent to every device, registered with the respective app, on which users have enabled push notifications.