Last week, my colleague Rajiv walked you through an overview of how our Mobility Services API now supports REST based APIs. As a developer for the Mobility Services Engine (MSE) team, I am very excited about this update because it means that it will be easier for developers to create apps using the MS-API, which hopefully means that more and more organizations will be able to take advantage of the location-based services and functionalities of the MSE. I'm going use this blog to walk you through some of the more technical aspects of the change.

The Basics

The REST API is now widely used in the field of API based web applications. The REST stands forREpresentationalStateTransfer. It is an architecture that is based on set of six rules, and APIs that support REST follow all those rules, making them RESTful.

Compared to SOAP, REST has better performance, scalability, simplicity, modifiability, visibility, portability, and reliability.For secured REST API transactions, HTTPS is recommended.

RESTful Mobility Services API

7.5 applications, including features from the Connected Mobile Experiences (CMX) solution such as Browser Engage and CMX Analytics, are now supporting REST APIs in addition to the existing SOAP APIs previous releases (backward compatibility).

CMX utilizes the basic authentication scheme to authenticate each REST API request. It utilizes the Authorization header in the HTTP packet. The Authorization header is composed as follows:

-Username and password are combined into a string "username:password".
-The resulting string literal is then encoded using Base64.
-The authorization method, a space and the string "Basic" is then put before the encoded string.

The API credentials can be accessed from Prime Infrastructure (PI), which manages CMX (page is located under Mobility Services > Specific MSE > System > Users).

As Rajiv mentioned last week, the Mobility Services REST APIs can be grouped in the following way:

-         MAP APIs

-         Real time location APIs

-         Location history APIs

-         Notification APIs

Let's break them down with use cases to get a better picture of when you'd use which.

MAP APIs

Cisco Prime Infrastructure configures CMX applications. It sends the floor maps data, including map images, to CMX as part of sync operation. The Access Points are placed in the floor map, and CMX determines the location of wireless devices with respect to AP placement in the map. Thus it is essential for third party applications that are interested to receive location data must retrieve floor maps data from the CMX.

The CMX provides following REST APIs for:

-          maps counts for specifying the number of Campuses, Buildings and Floors known to CMX

-          detailed information about all campuses, buildings, floors, Access Points, map dimensions, regions, zones, GPS markers, map images,  etc.

-          detailed information about specified campus or building, or floor

-          image associated with the specified campus or building, or floor

-          information on image for the specified image name

The MAP APIs can be used for the following use cases scenarios:

-          Identify how many campus, building and floors a CMX is monitoring for clients and other wireless entities (tags, rogues, and interferer) location

-          Load map images from CMX so that user can view the maps

-          Find out where APs are placed inside a floor

-          Get detailed map information so that the third party application can use the data to properly place clients and other wireless entities inside floor maps.

-          Find how many zones are defined in each floor and where they are place (position and dimension). Under floor, zone is the lowest level of denominator where CMX can monitor client location.

Real time Location APIs

The most important offering of Mobility Services REST APIs is the real time location data for all the tracked entities or a specified track entity. The CMX can track wireless clients, RFID tags, Rogue APs, Rogue clients and Interferers.

For each type of entity family, the Mobility Services REST API provides:

-          a count of entities on CMX based on the specified query parameters conditions.

-          a list of location of entities for the specified query conditions.

-          the location of an entity for the specified id. For the wireless client, the id can be mac address, IP address or username; for the remaining entity families (tags, rogues, interferer), the id is the mac address.

The MOBILITY SERVICES REST API s for real time location supports paging. When the number of entities is very large, it is better to receive data in chunks/blocks that is known aspaging. The default page size is 5000 i.e. in a single API call there can be at most 5000 records. When there is more than 1 page, thenextResourceURIwill specify the URI to the next resource. This is one of the advantages of using REST API -user does not need to remember from what index to query. Simply calling the next URI will fetch the next page. The last page will not have nextResourceURI.

The other powerful feature of Mobility Services REST APIs for real time location issorting. Sorting requests in the API requests is achieved by specifying query parameter "sortBy". If sorting order is not provided, the ascending sort order is assumed (default). To specify the sort order, the format to use is "sort parameter: order". For example, to request location results by lastLocatedTime in descending order, the required query parameter is "sortBy=lastLocatedTime:desc".  Please note that the query parameters are part of URI and they are preceded by "?" character.

Mobility Services REST APIs for real time location also supports multiple sort conditions by specifying "sortBy" query parameter multiple times. Some other query parameters are currentlyTracked, locatedAfterTime, locatedBeforeTime, mapHierarchy (wherever relevant).

There are hundreds of use cases that need to use the Mobility Services real time location APIs. They all involve with finding thecurrentlocation of specified wireless entities (clients, tags, rogues, interferer). Here are some of them:

• Monitor how many wireless clients are currently using the wireless network, and even find how many of them are in each floor or building or campus. This data will provide insight on current client usage in the network.
• Developing RTLS (real time location services).
  • RTLS system in health care monitors real time location of valuable assets, staff and patients in order to improve hospital workflows and thus it reduces cost.
  • RTLS system in brick-and-mortar retailer space allows owner to better manage their customers by sending more sales associate where customers are more concentrated.
  • RTLS system in manufacturing industries helps in locating resources in real time.
  • Locate the current position of a particular wireless client.
    • The client mac address may belong to a person of interest
    • This client mac address may belong to a laptop that is reported as stolen (in a university campus).
    • Receive notification/alert from PI that a rogue AP is detected and it is classified as malicious or unknown. Find the rogue AP current location to remove it from the premise to secure the wireless network from intrusion.
    • Receive notification/alert from PI that a rogue client is detected and it is classified as malicious or unknown. Find the rogue client current location to remove it from the premise to secure the wireless network from intrusion.
    • Find out the position of interferers as reported by Clean Air in PI so that they can be removed to improve the wireless communication.

Location History APIs

The CMX saves location history for all the tracked entities or a specified track entity. This feature allows user to view the movement history of tracked entities inside a floor. As mentioned before, the CMX can track wireless clients, RFID tags, Rogue APs, Rogue clients and Interferers.

For each type of entity family, the Mobility Services REST API provides:

-          a count of historical location records of entities on CMX based on the specified query parameters conditions.

-          a count of historical location records of an entity for the specified entity id and query conditions.

-          a list of history location records of entities for the specified query conditions.

-          a list of history location records of entity for the specified id and query conditions. For the wireless client, the id can be mac address, IP address or username; for the remaining entity families, the id is the mac address.

Like real time location APIs, the location history APIs also support paging and sorting.

The use cases for CMX location history APIs are related to real time location APIs, specifically where user needs to check/trace the movement history of an asset or a client. For example for missing tagged equipment, it can find when it was last reported to be seen and which location.

Notification APIs

Notification APIs are very useful as they generate event notifications when predefined events occur.  These APIs are mostly used to track wireless (WIFI) devices. The CMX provides event notifications for the following use case scenarios:

1. User is tracking a set of devices and he/she needs to get alert when any of them is absent for more than the specified time period (Absence event)
2. User has setup a number of RFID tags that have batteries. In case of battery power goes low, he/she needs to get alert that batteries need to be replaced (Battery event)
3. User wants to monitor the movement a set of assets that have attached RFID tags. As they pass in or out of a zone where Exciters are placed, he needs to get alerted (Exciter event)
4. User wants to know all the wireless devices that enter or leave a configured zone (Containment event)
5. User has set a number of RFID tags to secure his assets. If the RFID tags are detached or tampered, he/she needs to get alert so that the assets do not get lost/stolen (Emergency event)
6. User wants to track real time location of a set of wireless devices and he/she needs to get reported as these devices move more than a configured distance from its old location or a configured Marker (Movement event)
7. User wants to know any new wireless device that enters into his/her premise (Presence event)

Before concluding this blog, I like to show how to use REST APIs. Below is the sample code snippet to retrieve the client count.

1. You need to first create authorization string and set the url string.

String authorisation = mseUserName + ":" + msePassword;

byte[] encodedAuthorisation = Base64.encodeBase64(authorisation.getBytes());

String url = "http://" + mseIpAddress + "/api/contextaware/v1/location/clients/count/";

2. Next you need to create default http client and set the url and http header params

HttpClient client = new DefaultHttpClient(); //org.apache.http.impl.client.DefaultHttpClient

HttpGet request = new HttpGet(url);

// set http header params

request.addHeader("Accept", "application/json");

request.addHeader("Content", "application/json");

request.addHeader("Authorization", "Basic "+ new String(encodedAuthorisation));

3. Next execute the REST API call

// execute REST call with HTTP GET Request

HttpResponse response = null;

try {

    response = client.execute(request);

}

catch (Exception ex) {

     // handle exception here

}

Finally, check for valid response and if valid, convert it back to object

BufferedReader rd = null;

StringBuffer jsonResponse = new StringBuffer();

try {

    if (response.getEntity() != null) { 

        rd = new BufferedReader (new InputStreamReader(response.getEntity().getContent()));

        char[] array = new char[1];

        while ((rd.read(array) != -1)) {

            jsonResponse.append(array);

         }

        System.out.println(jsonResponse.toString());          

    }  

}

catch (IOException ioe) {

    // handle exception here

}

 

// for client count corresponding object is DeviceCount

// convert json response into DeviceCount class if jsonResponse is valid

try {

    ObjectMapper mapper = new ObjectMapper();

    mapper.configure(DeserializationConfig.Feature.FAIL_ON_UNKNOWN_PROPERTIES, false);

    int offset = "DeviceCount.class".indexOf(".class") + 4; // exclude root field from json string

    int len = jsonResponse.toString().length() -1; // exclude root field from json string

    DeviceCount deviceCount = mapper.readValue(jsonResponse.toString().getBytes(), offset,   

        len, DeviceCount.class);        

    System.out.println(deviceCount.toString());

} catch (Exception e) {

    // handle exception here

}

I hope you now understand a bit more about how Mobility Services REST APIs can be applied in the real world. Our goal is for the Mobility Services REST APIs to deliver a powerful and efficient, yet simple interface to retrieve location related data from the MSE so that the Connected Mobile Experiences solution can deliver the greatest value to your organization by enhancing the mobile experience.

For more on the Mobility Services REST API or to check it out yourself, visit http://developer.cisco.com/web/mobility-services/home.

We love to hear feedback how we can improve or extend them further. We'll be taking questions on this blog and on our Mobility Community discussion forum.