Introduction

This document is a guide for consuming the MGB Api through the MGB Rest Service.
There are two main categories of client applications: web applications and distributed applications. Web applications will only be deployed on web servers while distributed applications will be deployed on the end users’ machines.

Anatomy of a MGB Rest Service call

Each call to the MGB Rest Service should respect the following rules:

•    all calls will be made using HTTP requests using the POST method

•    all calls represent methods exposed by the MGB Rest Service. All method names will be represented as relative URLs. For example: userLocation/updateUserLocationManually 

•    the URLs of the http requests will be composed by concatenating the service’s base URL and the relative URL of the method. For example: http://serviceDomain/RestAPI.svc/userLocation/updateUserLocationManually 

•    method parameters will be transmitted inside the body of the HTTP request as form urlencoded strings. The body of the request would look in the same way as the query parameters from an URL, but will have no length limit: param1=value1&param2=value2&...&paramN=valueN. All parameter values must be encoded using URL encoding (http://en.wikipedia.org/wiki/Percent-encoding#The_application.2Fx-www-form-urlencoded_type).

•    all http requests must have the following content type header defined: Content-Type: application/x-www-form-urlencoded

Request/response format

Inside a request call, all parameters that have values of base types will be directly serialized as strings. Base types are numerical types, strings, booleans, dates. For example:

lon=40.2345&lat=41.5432
Complex types passed as parameters and the HTTP response will be formatted using either XML or JSON. For example if we have a complex type named User that consists in two string fields named FirstName and LastName and an int field named Age, it will be serialized as xml in the following way:
<User><Age>26</Age><FirstName>Florin</FirstName><LastName>Dumitrescu</LastName></User>

and as Json like this:
{"Age":26,"FirstName":"Florin","LastName":"Dumitrescu"}

Also, responses will be formatted using xml or Json even if they are of base types. For example, if the response for a request consists in the Barcelona string, it will be formatted like <string>Barcelona</string> if the response format is xml and like “Barcelona” if the response format is Json.

The caller can control the format type for request parameters and responses in each request by passing to each method a parameter called format that can have one of the following two values: xml or json. The default format for a MGB Rest Service call is Json.

Every complex type that would be used by the MGB Rest Service would be described in its documentation.

Null values

For request parameters of base types

If you want to call a method and pass null to the value of one of its parameters that is of a base type, there are two ways to do that:

1.    Do not pass the parameter to the request. For example, if you have three parameters and you want param2 to be null, you can build the request with the following parameters: param1=value1&param3=value3.

2.    Do not supply any value for the parameter. In the same context as the previous example, you would have to build the request with the following parameters: param1=value1&param2=&param3=value3.

For xml formatted values

Nulls for xml formatted values are represented as described by the W3C in the XML Schema specification: http://www.w3.org/TR/xmlschema-1/#xsi_nil.

For example, the following User object has the LastName field as null:
<User><Age>26</Age><FirstName>Florin</FirstName><LastName i:nil="true"/></User>

For json formatted values

As described in the Json specification, http://www.json.org/, null values are represented with the null keyword.

For example, the following User object has the LastName field as null:
{"Age":26,"FirstName":"Florin","LastName":null}

Arrays

This section describes how arrays should be formated when sent as parameters to the API methods. The same rules also apply when reading array replies from the API.

For xml format

The following pattern si used when serializing arrays in the xml format:
<ArrayOfMyType xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <MyType>value1</MyType>
    <MyType>value2</MyType>
    ...
    <MyType>valueN</MyType>
</ArrayOfMyType>
MyType needs to be replaced with the type of the array being serialized. The xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays" namespace is mandatory. Bellow is an example for representing an array of string:
<ArrayOfstring xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays"><string>London</string><string>Bucharest</string><string>Berlin</string></ArrayOfstring>

For json format

The API uses the standard format for serializing arrays, as described on the json official web site www.json.org. For example, an array of strings would be represented like this:
["London","Bucharest","Berlin"]

Representing date and time

Dates and date times must be represented as strings according to a subset of the iso 8601:2004 standard, that can be found in here: http://www.w3.org/TR/NOTE-datetime.

For example a date in summer time (Daylight Saving Time) in Denmark, would be represented like this:
2009-05-24T18:57:30.359375+02:00

Security

Message signature

Each MGB Rest Service method that needs security will require the following parameters:

•    appKey – any client application that needs to communicate with the MGB Rest Service will need to register on MGB and will receive a unique GUID string called appKey. This string needs to be passed with this parameter.

•    sessionId – after an MGB user signs in inside the client application, the client application will receive a sessionId from MGB that the application will use in order to make calls to MGB on behalf of the user.

•    callId – the callId is an int64 number that must be unique and greater than the last callId for each service call on the same session. You should get this number from a function that returns the current date and time in milliseconds. The callId should always be greater than zero.

•    sig – the signature for the current message.

You compute the signature by applying the and MD5 over the following string: appKey + sessionId + callId.toString() + appSecret.

For web application clients, the appSecret is a GUID string that is received when registering the application in MGB at the same time the appKey is received. The appSecret should be kept secret by the client application.

Unlike web applications, distributed client applications can be disassembled or have their memory analyzed by attackers, which means that they would not be able to keep an permanent appSecret that would be common to all the instances of the distributed application. To solve this problem, a client distributed application will receive a temporary appSecret at the time it is also receiving the sessionId.

Here is an example of a computed signature:
appKey = dc630623027e45aaa135e95bce506573
sessionId = 1304dc5cb3c2452cb917132ac262f10c
callId = 633788053654687500
appSecret = 9fded58cefbe4f928e830ca1d0d811f2
sig = aa95afc57e8b451200a9a004189702e5

Getting the sessionId and the temporary appSecret

Web application clients need to call the following method in order to get their sessionId: security/createSessionForWebApp.

Distributed application clients need to call the following method in order to get their sessionId and their temporary appSecret: security/createSessionForDistributedApp.

Errors

Every successful call response from the MGB Rest Service has an HTTP status code of 200 (which is the HTTP OK status code). Every time an error ocurres on the server, the response would have an error status code (4xx if the error came as a result of bad caller imput, 5xx if the error is an internal server error).
Besides, the HTTP error status code, error responses will also contain an error description  object in their body, which consists in two fields:

•    Description – which is an human readable string describing the error

•    ErrorCode – which represents the code of the error. A list with the error codes returned by the MGB Rest Sevice will be published in a separate document.

Here is an example of an error response in the JSON format:
{"Description":"Invalid value for the appKey parameter","ErrorCode":101}
Here is an example of an error response in the XML format:
<RestException.ErrorInfo>
<Description>Invalid value for the appKey parameter</Description>
<ErrorCode>101</ErrorCode>
</RestException.ErrorInfo>

There are cases when an error ocurres on the server in another place than those controlled by the MGB Rest Service code, the response will no longer contain an error description like that presented above.