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:
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:
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.