Documentation : HTTP API References

When to use

The HTTP API lets you interact with Mobeelizer from any components that can send a HTTP request. Common solution could be creation of client adapter that cooperate beetwen Mobeelizer Cloud and Enterprise App to sync your application data with your mobiles. There are many things you can do with the HTTP API. Some examples are:

  • You can easily sync data between your app and mobile clients.
  • You can upload part of your app data that will later be consumed in a mobile app with offline mode.
  • You can get recent data to do some reports or custom analytics in your Enterprise App.
  • You can sync your app files between your app and mobile clients.
  • You can get some conflicts on the data and resolve them in your application.
  • You can put your users (i.e. LDAP) to your application definition on Mobeelizer.
  • You can create application in any programming language which can sync data with Mobeelizer.

Overview

HTTP API is the interface to the Mobeelizer Cloud via HTTP protocol. Every request must have following headers.

Header

Description

mas-vendor-name

vendor's name - log in to App Designer -> Vendor's name is on the top of the page.

mas-application-name

application's name - log in to App Designer -> Select app -> Application's name is in the top left corner of the page.

mas-application-instance-name

instance's name - log in to App Designer -> Select app -> go to Test or Use tab -> Manage environments -> Column name

mas-definition-digest

definition's digest - log in to App Designer -> Select app -> Versions -> Select version -> More Info -> Show version digest

mas-device-name

device category's name - log in to App Designer -> Select app -> Groups & Roles -> Device categories -> Column name

mas-device-identifier

unique device's identifier, e.g. MAC address, IP

mas-user-name

login - log in to App Designer -> Select app -> go to Test or Use tab -> Users -> Column name

mas-user-password

password - log in to App Designer -> Select app -> go to Test or Use tab -> Users -> Edit

Data format

Entity JSON

  • model - model's name

  • guid - entity's guid

  • owner - entity's owner

  • resolveConflict - if true, conflict of that entity will be resolved

  • conflictState - entity's conflict state, possible values: NO_IN_CONFLICTIN_CONFLICTIN_CONFLICT_BECAUSE_OF_YOU

  • fields - map of the fields, where the key is the field's name

The field s_deleted must exist. It indicates if the entity is removed or not.

The owner and conflictState are ignored in "request synchronization" operation.

{
	"model" : "entity's model",
	"guid" : "entity's guid",
	"owner" : "entity's owner",
	"resolveConflict" : "false / true",
	"conflictState" : "entity's conflict state",
	"fields" : { 
		"s_deleted" : "false / true",
		"field's name" : "field's value",
		"other field's name" : "other field's value",
    	...
	}
}

Binary data request and response

The binary data (request for "request synchronization" operation and response for "get synchronization data" operation) is the ZIP file with at least two files: 

  • data - file with entities to synchronize, every line is one entity represented as valid JSON
  • deletedFiles - file with guids of the files to delete, every line is one guid

Additionally ZIP can contain file to insert. The name of the file must be equal to its guid.

JSON Response

Successful response

The HTTP status is 200.

// the response body as JSON specified in operations

Failure response

This failure is caused by invalid configuration or user input. The HTTP status is 500.

{
	"messageCode" : "error code",
	"message" : "error message"
    "arga" : [ 
		// message args
	]
}

The error codes:

  • vendorNotFound - vendor from mas-vendor-name header doesn't exist
  • applicationNotFound - application from mas-application-name header doesn't exist
  • instanceNotFound - instance from mas-application-instance-name header doesn't exist
  • definitionNotFound - definition with digest from mas-definition-digest header doesn't exist
  • deviceNotFound - device from mas-device-identifier header doesn't exist
  • authenticationFailure - authentication error for login and password from mas-user-name and mas-user-password headers
  • syncException - synchronization error

  • other - unspecified error, see message for more info

Operations

Authenticate

Authenticate user and return its role and instance guid.

https://cloud.mobeelizer.com/sync/v2/authenticate

Method: GET

Parameters:

  • deviceType - optional, in case that cliect will receive the push notifications it has to equal to "http"
  • deviceToken - optional, in case that cliect will receive the push notifications it has to be an URL that point to the push notifications service 

Content type: application/json

Response:

{ 
	"role" : "user role",
	"instanceGuid" : "instance guid"
}

Request Full Synchronization

Request full synchronization and return the ticket for the synchronization task.

https://cloud.mobeelizer.com/sync/v2/synchronizeAll

Method: POST

Parameters: none

Content type: application/json

Response:

"ticket for synchronization task"

Request Synchronization

Request synchronization and return the ticket for the synchronization task. Request body contains ZIP file with data to synchronize.

https://cloud.mobeelizer.com/sync/v2/synchronize

Method: POST

Parameters: none

Request: binary file with data to synchronize under the name "file"

Content type: multipart/form-data

Response:

"ticket for synchronization task"

Check Synchronization Status

Check status of task with given ticket. Possible statuses:

  • WAITING - task is waiting for being processing

  • PENDING - task is being currently processing

  • FINISHED - task has been finished with success

  • REJECTED - task has been finished with failure

  • CONFIRMED - task has been already confirmed

Additional information about the status REJECTED can be found in the result and message. Result can have one of these values:

  • ACCESS_DENIED - cannot modify field or model without permission

  • NOT_VALID - some of entity is not valid 

  • PARSE_ERROR -  some of entity has invalid JSON

  • INTERNAL_ERROR - other error

https://cloud.mobeelizer.com/sync/v2/checkStatus

Method: GET

Parameters:

  • ticket - ticket for synchronization task

Content type: application/json

Response: 

{
	"status" : "task status",
	"result" : "error of rejected synchronization",
	"message" : "error message of rejected synchronization"
}

Get Synchronization Data

https://cloud.mobeelizer.com/sync/v2/data

Method: GET

Parameters:

  • ticket - ticket for synchronization task

Content type: application/json

Response: binary file with data to synchronize

Confirm Synchronization

https://cloud.mobeelizer.com/sync/v2/confirm

Method: POST

Parameters:

  • ticket - ticket for synchronization task

Content type: application/json

Response:

// empty

Get Conflict History

https://cloud.mobeelizer.com/sync/v2/conflictHistory

Method: GET

Parameters:

  • model - name of conflicted entity model

  • guid - guid of conflicted entity

Content type: application/json

Response: binary file with versions data

Http errors:

  • NOT FOUND (404) - entity is not in conflict state.  
  • BAD REQUEST (400) - model or entity does not exist.
  • METHOD NOT ALLOWED  (405)- manual conflict resolving is disabled or user does not have permission to resolve conflicts. 
  • INTERNAL ERROR (500) - other error.

Send Push Notification

https://cloud.mobeelizer.com/sync/v2/push

Method: POST

Parameters: none

Request:

{
	"notification" : {
		"key1" : "value1",
		"key2" : "value2"
	},
	"device" : "device category name",
	"group" : "group name",
	"users" : ["user1", "user2"]
}

where:

parameter

required

type

description

notification

yes

map string -> string

content of notification

device

no

string

name of device category to which send messages

group

no

string

name of group to which send messages

users

no

array of strings

names of users to which send messages

Content type: application/json

Response:

// empty

User management

To manage users you have to authenticate with user with admin permission. See users page for more info.

Get user details

Returns details of user by its login

https://cloud.mobeelizer.com/sync/v2/client/user/get

Method: GET

Parameters:

  • login - login of user to get

Content type: application/json

Response:

{
	"login" : "user login",
	"mail" : "user mail",
	"group" : "user group",
	"admin" : false // or true
}

Get users list

Returns list of all users

https://cloud.mobeelizer.com/sync/v2/client/user/list

Method: GET

Parameters: none

Content type: application/json

Response:

[
	{
		"login" : "user login",
		"mail" : "user mail",
		"group" : "user group",
		"admin" : false // or true
	},
	// ... other users
]

Get groups

Returns list of available user groups

https://cloud.mobeelizer.com/sync/v2/client/user/groups

Method: GET

Parameters: none

Content type: application/json

Response:

["group1", "group2",...]

Create user

Creates new user

https://cloud.mobeelizer.com/sync/v2/client/user/create

Method: POST

Parameters: none

Content type: application/json

Request:

{
	"login" : "user login",
	"password" : "user password",
	"mail" : "user mail",
	"group" : "user group",
	"admin" : false // or true
}

where:

parameter

required

type

description

login

yes

string

login of new user

password

yes

string

password for new user

mail

no

string

mail of user

group

yes

string

group that this user belongs

adminyesbooleantrue if user should be admin, false otherwise

See users page for more info.

Response:

// empty

Update user

Updates existing user

https://cloud.mobeelizer.com/sync/v2/client/user/update

Method: POST

Parameters: none

Content type: application/json

Request:

{
	"login" : "user login",
	"password" : "user password",
	"mail" : "user mail",
	"group" : "user group",
	"admin" : false // or true
}

where:

parameter

required

type

description

login

yes

string

login of existing user

password

no

string

new password of user, if no password property then user password won't be changed

mail

no

string

new mail of user

group

yes

string

new group that this user belongs

adminyesbooleantrue if user should be admin, false otherwise

See users page for more info.

Response:

// empty

Delete user

Deletes existing user

https://cloud.mobeelizer.com/sync/v2/client/user/delete

Method: POST

Parameters:

  • login - login of user to get

Content type: application/json

Response:

// empty

Web service for push notifications

The web service will consume push notification and so that it is only required when the client should received these notifications.

It will reveice HTTP Post requests with the body that contains notification object - the "notification" map that have been sent using send push notification operation. Optionally it is possible to secure web service using HTTP Basic Authorization. If so the login and password must be set in App Designer in "Push notifications" section.

The address of this service is pass as parameter of the authenticate operation.