REST APIs on MSE
One of the coolest new features of MSE in this latest release, is the addition of REST API support on the MSE. The sections below describes the various APIs', as well as the schema invloved with those API calls.
Authentication for REST API
MSE APIs uses Basic Authentication scheme to authenticate the API request. Each API Request,
should contain the API access credentials in the Authorization header.
The API credentials can be generated by the MSE Admin via the NCS by going to the Users and Groups page of the MSE.
This page is located on NCS at Mobility Services > Specific MSE > System > Users
Note, that the user credentials have read and write permissions associated with it. User
credentials without write permissions can only perform 'GET' operations on the REST API resources.
In addition, certain APIs will only return the configurations created by the requesting user.
The Authorization header is constructed as follows:
1. Username and password are combined into a string "username:password".
2. The resulting string literal is then encoded using Base64.
3. The authorization method, a space and the string "Basic" is then put before the encoded string.
For example, if the username is 'Aladin' and the password is 'sesame open', then the header is formed as follows:
Authorization: Basic QxhZGluOnNlc2FtIG9wZW4=
If the API request doesn't have Authorization header or if the credentials are incorrect, then
the MSE will send a HTTP 401 Not Authorized response code containing the authenticate header as below:
WWW-Authenticate: Basic realm="MSE API Service"
should contain the API access credentials in the Authorization header.
The API credentials can be generated by the MSE Admin via the NCS by going to the Users and Groups page of the MSE.
This page is located on NCS at Mobility Services > Specific MSE > System > Users
Note, that the user credentials have read and write permissions associated with it. User
credentials without write permissions can only perform 'GET' operations on the REST API resources.
In addition, certain APIs will only return the configurations created by the requesting user.
The Authorization header is constructed as follows:
1. Username and password are combined into a string "username:password".
2. The resulting string literal is then encoded using Base64.
3. The authorization method, a space and the string "Basic" is then put before the encoded string.
For example, if the username is 'Aladin' and the password is 'sesame open', then the header is formed as follows:
Authorization: Basic QxhZGluOnNlc2FtIG9wZW4=
If the API request doesn't have Authorization header or if the credentials are incorrect, then
the MSE will send a HTTP 401 Not Authorized response code containing the authenticate header as below:
WWW-Authenticate: Basic realm="MSE API Service"
REST APIs for Context Aware Service
Various APIs associated with the Context Aware Service are listed below. They are broadly classified into three categories.
Map API
The Maps API provides details about the Map data. This includes the Campus, Buildings, Floors, Zones, Access Points, Dimensions, Map Images, GPS Markers, Obstacles, LocationFilterRegions and Exciters.
The APIs support xml and json data formats. The response is determined based on the Accept HTTP header
For XML data format, use Accept: application/xml and for JSON data format, use Accept: application/json
All Map API request need an Authorization header. See Authentication for more details.
/api/contextaware/v1/maps/count
Method: GET
Returns Maps Count specifying the number of Campuses, Buildings and Floors known to MSE.
Accepts
/api/contextaware/v1/maps
Method: GET
Returns detailed Map Information about Campuses, Buildings, Floors, Access Points, Map Dimensions, Regions, Zones, GPS Marker, Image information etc.
Accepts
/api/contextaware/v1/maps/info/{campusName}/{buildingName}/{floorName}
Parameters
Returns all the floor information associated with the campusName -> buildingName -> floorNameThis includes floor dimension, Access Points and their information, GPS Markers etc.
Accepts
Parameters
Returns the floor image associated with the campusName -> buildingName -> floorName
Accepts
Parameters
Returns the image associated with the specified imageName
Accepts
Parameters
Returns the building image associated with the campusName -> buildingName
Accepts
/api/contextaware/v1/maps/info/{campusName}
Parameters
Returns the Campus information associated with the campusName
Accepts
Parameters
Returns the campus image associated with the campusName
Accepts
/api/contextaware/v1/maps/info/{campusName}/{buildingName}/
Parameters
Returns the Building information associated with the campusName -> buildingName
Accepts
The APIs support xml and json data formats. The response is determined based on the Accept HTTP header
For XML data format, use Accept: application/xml and for JSON data format, use Accept: application/json
All Map API request need an Authorization header. See Authentication for more details.
/api/contextaware/v1/maps/count
Method: GET
Returns Maps Count specifying the number of Campuses, Buildings and Floors known to MSE.
Accepts
- application/json
- application/xml
- 200 Successful response
- 500 Server Error
/api/contextaware/v1/maps
Method: GET
Returns detailed Map Information about Campuses, Buildings, Floors, Access Points, Map Dimensions, Regions, Zones, GPS Marker, Image information etc.
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 MSE does not have any Map Information
- 500 Server Error
/api/contextaware/v1/maps/info/{campusName}/{buildingName}/{floorName}
Parameters
- floorName Name of the required floor.
- buildingName Name of the required building.
- campusName Name of the required campus.
Returns all the floor information associated with the campusName -> buildingName -> floorNameThis includes floor dimension, Access Points and their information, GPS Markers etc.
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 No floor with the specified campusName -> buildingName -> floorName
- 500 Server Error
Parameters
- floorName Name of the required floor.
- buildingName Name of the required building.
- campusName Name of the required campus.
Returns the floor image associated with the campusName -> buildingName -> floorName
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 No image with the specified campusName -> buildingName -> floorName
- 500 Server Error
Parameters
- imageName Name of the required image
Returns the image associated with the specified imageName
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 No image with the specified imageName
- 500 Server Error
Parameters
- buildingName Name of the required building.
- campusName Name of the required campus.
Returns the building image associated with the campusName -> buildingName
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 No image with the specified campusName -> buildingName
- 500 Server Error
/api/contextaware/v1/maps/info/{campusName}
Parameters
- campusName Name of the required campus.
Returns the Campus information associated with the campusName
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 No campus with the specified campusName
- 500 Server Error
Parameters
- campusName Name of the required campus.
Returns the campus image associated with the campusName
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 No image with the specified campusName
- 500 Server Error
/api/contextaware/v1/maps/info/{campusName}/{buildingName}/
Parameters
- buildingName Name of the required Building.
- campusName Name of the required campus.
Returns the Building information associated with the campusName -> buildingName
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 No building with the specified campusName -> buildingName combination
- 500 Server Error
Real Time Location APIs
The Real time Location APIs gives access to the location of devices that are currently being tracked by the MSE The APIs support xml and json data formats. The response is determined based on the Accept HTTP header For XML data format, use Accept: application/xml and for JSON data format, use Accept: application/json All Location APIs request need an Authorization header. See Authentication for more details.
Paging
Pagination in the resources is done by specifying queryParams "page" and "pageSize". The default pagesize is 5000. When there is more than 1 page, the nextResourceURI will specify the URI to the next resource.
Sorting
Sorting requests in the API requests is achieved by specifying queryParams "sortBy". By default, ascending sort order is assumed. To specify the sort order use format "sort parameter: order" For example, to request location results by lastLocatedTime in descending order specify queryParams "sortBy=lastLocatedTime:desc" For multiple sort conditions, use multiple "sortBy" queryParams.
/api/contextaware/v1/location/clients/{id}
Parameters
Returns the Location of Wireless Client for the specified id. The id can be MacAddress, IPAddress or Username
Accepts
/api/contextaware/v1/location/clients{?}
Parameters
Returns a list of Location of Wireless Clients for the specified query conditions.
Accepts
Schema
Parameters
Returns a count of Wireless Clients on MSE based on the specified Query Param conditions.
Accepts
Schema
/api/contextaware/v1/location/tags{?}
Parameters
Returns a list of Location of Tags for the specified query conditions.
Accepts
Schema
/api/contextaware/v1/location/tags/{id}
Parameters
Returns the Location of Tag for the specified id.
Accepts
/api/contextaware/v1/location/tags/count{?}
Parameters
Returns a count of Tags on MSE based on the specified Query Param conditions.
Accepts
Schema
/api/contextaware/v1/location/rogueaps/count{?}
Parameters
Returns a count of Rogue APs on MSE based on the specified Query Param conditions.
Accepts
Schema
/api/contextaware/v1/location/rogueaps{?}
Parameters
Returns a list of Location of Rogue APs for the specified query conditions.
Accepts
Schema
/api/contextaware/v1/location/rogueaps/{id}
Parameters
Returns the Location of Rogue AP for the specified id.
Accepts
/api/contextaware/v1/location/rogueclients/{id}:
Parameters
Returns the Location of Rogue Client for the specified id.
Accepts
/api/contextaware/v1/location/rogueclients/count{?}
Parameters
Returns a count of Rogue Clients on MSE based on the specified Query Param conditions.
Accepts
Schema
/api/contextaware/v1/location/rogueclients{?}
Parameters
Returns a list of Location of Rogue Clients for the specified query conditions.
Accepts
Schema
/api/contextaware/v1/location/interferers/{id}
Parameters
Returns the Location of Interferer for the specified id.
Accepts
/api/contextaware/v1/location/interferers/count{?}
Parameters
Returns a count of Interferers on MSE based on the specified Query Param conditions.
Accepts
Schema
/api/contextaware/v1/location/interferers{?}
Parameters
Returns a list of Location of Interferers for the specified query conditions.
Accepts
Schema
Paging
Pagination in the resources is done by specifying queryParams "page" and "pageSize". The default pagesize is 5000. When there is more than 1 page, the nextResourceURI will specify the URI to the next resource.
Sorting
Sorting requests in the API requests is achieved by specifying queryParams "sortBy". By default, ascending sort order is assumed. To specify the sort order use format "sort parameter: order" For example, to request location results by lastLocatedTime in descending order specify queryParams "sortBy=lastLocatedTime:desc" For multiple sort conditions, use multiple "sortBy" queryParams.
/api/contextaware/v1/location/clients/{id}
Parameters
- id Macaddress, IP Address or Username of the wireless client.
Returns the Location of Wireless Client for the specified id. The id can be MacAddress, IPAddress or Username
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 If there is no Wireless client for the specified id.
- 500 Server Error
/api/contextaware/v1/location/clients{?}
Parameters
- Defines query conditions for the Wireless Client
Returns a list of Location of Wireless Clients for the specified query conditions.
Accepts
Schema
- application/json
- WirelessClientApiQueryParams {"type":"object","properties":{"mapHierarchy":{"type":"string"},"currentlyTracked":{"type":"boolean","required":true},"locatedAfterTime":{"type":"string"},"locatedBeforeTime":{"type":"string"},"sortBy":{"type":"array","items":{"type":"string"}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"dot11Status":{"type":"string","enum":["UNKNOWN","ASSOCIATED","PROBING"]},"associatedApMac":{"type":"string"},"ssid":{"type":"string"}}}
- WirelessClientApiQueryParams {"type":"object","properties":{"mapHierarchy":{"type":"string"},"currentlyTracked":{"type":"boolean","required":true},"locatedAfterTime":{"type":"string"},"locatedBeforeTime":{"type":"string"},"sortBy":{"type":"array","items":{"type":"string"}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"dot11Status":{"type":"string","enum":["UNKNOWN","ASSOCIATED","PROBING"]},"associatedApMac":{"type":"string"},"ssid":{"type":"string"}}}
- Return codes
- 200 Successful response
- 404 If there are no Wireless clients for the specified query conditions.
- 500 Server Error
- 200 Successful response
Parameters
- Defines query conditions for the Wireless Client
Returns a count of Wireless Clients on MSE based on the specified Query Param conditions.
Accepts
Schema
- application/json
- WirelessClientApiQueryParams {"type":"object","properties":{"mapHierarchy":{"type":"string"},"currentlyTracked":{"type":"boolean","required":true},"locatedAfterTime":{"type":"string"},"locatedBeforeTime":{"type":"string"},"sortBy":{"type":"array","items":{"type":"string"}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"dot11Status":{"type":"string","enum":["UNKNOWN","ASSOCIATED","PROBING"]},"associatedApMac":{"type":"string"},"ssid":{"type":"string"}}}
- WirelessClientApiQueryParams {"type":"object","properties":{"mapHierarchy":{"type":"string"},"currentlyTracked":{"type":"boolean","required":true},"locatedAfterTime":{"type":"string"},"locatedBeforeTime":{"type":"string"},"sortBy":{"type":"array","items":{"type":"string"}},"page":{"type":"integer"},"pageSize":{"type":"integer"},"dot11Status":{"type":"string","enum":["UNKNOWN","ASSOCIATED","PROBING"]},"associatedApMac":{"type":"string"},"ssid":{"type":"string"}}}
- 500 Server Error
- 200 Successful response
/api/contextaware/v1/location/tags{?}
Parameters
- Defines query conditions for the Tag
Returns a list of Location of Tags for the specified query conditions.
Accepts
Schema
- application/json
- application/xml
- 200 Successful response
- 404 If there are no Tags for the specified query conditions.
- 500 Server Error
/api/contextaware/v1/location/tags/{id}
Parameters
- id MacAddress of the Tag
Returns the Location of Tag for the specified id.
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 If there is no Tag for the specified id.
- 500 Server Error
/api/contextaware/v1/location/tags/count{?}
Parameters
- Defines query conditions for the Tag
Returns a count of Tags on MSE based on the specified Query Param conditions.
Accepts
Schema
- application/json
- application/xml
- 200 Successful response
- 500 Server Error
/api/contextaware/v1/location/rogueaps/count{?}
Parameters
- Defines query conditions for the Rogue AP
Returns a count of Rogue APs on MSE based on the specified Query Param conditions.
Accepts
Schema
- application/json
- application/xml
- 200 Successful response
- 500 Server Error
/api/contextaware/v1/location/rogueaps{?}
Parameters
- Defines query conditions for the Rogue AP
Returns a list of Location of Rogue APs for the specified query conditions.
Accepts
Schema
- application/json
- application/xml
- 200 Successful response
- 404 If there are no Rogue APs for the specified query conditions.
- 500 Server Error
/api/contextaware/v1/location/rogueaps/{id}
Parameters
- id MacAddress of the Rogue AP
Returns the Location of Rogue AP for the specified id.
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 If there is no Rogue AP for the specified id.
- 500 Server Error
/api/contextaware/v1/location/rogueclients/{id}:
Parameters
- id MacAddress of the Rogue Client
Returns the Location of Rogue Client for the specified id.
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 If there is no Rogue Client for the specified id.
- 500 Server Error
/api/contextaware/v1/location/rogueclients/count{?}
Parameters
- Defines query conditions for the Rogue Client
Returns a count of Rogue Clients on MSE based on the specified Query Param conditions.
Accepts
Schema
- application/json
- application/xml
- 200 Successful response
- 500 Server Error
/api/contextaware/v1/location/rogueclients{?}
Parameters
- Defines query conditions for the Rogue Client
Returns a list of Location of Rogue Clients for the specified query conditions.
Accepts
Schema
- application/json
- application/xml
- 200 Successful response
- 404 If there are no Rogue Clients for the specified query conditions.
- 500 Server Error
/api/contextaware/v1/location/interferers/{id}
Parameters
- id MacAddress of the Interferer
Returns the Location of Interferer for the specified id.
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 If there is no Interferer for the specified id.
- 500 Server Error
/api/contextaware/v1/location/interferers/count{?}
Parameters
- Defines query conditions for the Interferers
Returns a count of Interferers on MSE based on the specified Query Param conditions.
Accepts
Schema
- application/json
- application/xml
- 200 Successful response
- 500 Server Error
/api/contextaware/v1/location/interferers{?}
Parameters
- Defines query conditions for the Interferers
Returns a list of Location of Interferers for the specified query conditions.
Accepts
Schema
- application/json
- application/xml
- 200 Successful response
- 404 If there are no Interferer for the specified query conditions.
- 500 Server Error
Navigation API
MSE provides a Navigation API to give the shortest path between two points. Use one of the APIs below:
Navigate from (A,B) to (C,D)
http://cmx-mse-5:8081/Mario/services/rs/mapservice/getShortestPath/551?sourcex=A&sourcey=B&targetx=C&targety=D
http://cmx-mse-3:8081/Mario/services/rs/mapservice/getShortestPath/601?sourcex=A&sourcey=B&targetx=C&targety=D
http://cmx-mse-2:8081/Mario/services/rs/mapservice/getShortestPath/551?sourcex=A&sourcey=B&targetx=C&targety=D
http://cmx-mse-1:8081/Mario/services/rs/mapservice/getShortestPath/551?sourcex=B&sourcey=B&targetx=C&targety=D
Sample response :
{"path":[{"x":6.436702458611849,"y":71.93193019344118,"id":"1372452160436","attributes":{"id":"1372452160436","type":"navNode"}},{"x":6.790610497573326,"y":102.01416422267856,"id":"1372452158979","attributes":{"id":"1372452158979","type":"navNode"}},{"x":66.60106908206282,"y":103.42979876523091,"id":"1372452155652","attributes":{"id":"1372452155652","type":"navNode"}},{"x":120.74899904316868,"y":102.72198149395473,"id":"1372452153994","attributes":{"id":"1372452153994","type":"navNode"}},{"x":147.29210196527941,"y":101.30634695140239,"id":"1372452171092","attributes":{"id":"1372452171092","type":"navNode"}},{"x":165.69531999127616,"y":103.07589012959282,"id":"1372452151215","attributes":{"id":"1372452151215","type":"navNode"}},{"x":167.11095214712208,"y":146.9605609487156,"id":"1372452150006","attributes":{"id":"1372452150006","type":"navNode"}}]}
Navigate from (A,B) to (C,D)
http://cmx-mse-5:8081/Mario/services/rs/mapservice/getShortestPath/551?sourcex=A&sourcey=B&targetx=C&targety=D
http://cmx-mse-3:8081/Mario/services/rs/mapservice/getShortestPath/601?sourcex=A&sourcey=B&targetx=C&targety=D
http://cmx-mse-2:8081/Mario/services/rs/mapservice/getShortestPath/551?sourcex=A&sourcey=B&targetx=C&targety=D
http://cmx-mse-1:8081/Mario/services/rs/mapservice/getShortestPath/551?sourcex=B&sourcey=B&targetx=C&targety=D
Sample response :
{"path":[{"x":6.436702458611849,"y":71.93193019344118,"id":"1372452160436","attributes":{"id":"1372452160436","type":"navNode"}},{"x":6.790610497573326,"y":102.01416422267856,"id":"1372452158979","attributes":{"id":"1372452158979","type":"navNode"}},{"x":66.60106908206282,"y":103.42979876523091,"id":"1372452155652","attributes":{"id":"1372452155652","type":"navNode"}},{"x":120.74899904316868,"y":102.72198149395473,"id":"1372452153994","attributes":{"id":"1372452153994","type":"navNode"}},{"x":147.29210196527941,"y":101.30634695140239,"id":"1372452171092","attributes":{"id":"1372452171092","type":"navNode"}},{"x":165.69531999127616,"y":103.07589012959282,"id":"1372452151215","attributes":{"id":"1372452151215","type":"navNode"}},{"x":167.11095214712208,"y":146.9605609487156,"id":"1372452150006","attributes":{"id":"1372452150006","type":"navNode"}}]}
Notification Events APIs
The Notification Event APIs allows an application to register for Push Notifications from the MSE. The following Notification Events are supported:
1. Absence Event -- Triggers a notification if subscribed devices is absent for the configured absent interval.
2. Battery Event -- Triggers a notification if the battery level of a RFID tag is at the configured level.
3. Exciter Event -- Triggers a notification if the RFID Tag is detected by a configured Exciter.
4. Containment Event -- Triggers a notification if a device is inside or outside of a configured zone.
5. Emergency Event -- Triggers a notification if the Emergency or Panic button on the RFID Tag is pressed.
6. MapInfoChange Event -- Triggers a notification if the Map configuration on MSE changes.
7. Movement Event -- Triggers a notification if a device moves more than a configured distance from its old location or a configured Marker.
8. Presence Event -- Triggers a notification when a device is first detected by the MSE.
9. Streaming Notifications -- Triggers a stream of notification for every location calculation
The above notifications can be configured for a specific macaddress, a list of mac address and with wildcard for a specific device Type.
The Notification Events can be configured to be sent in one of the following 3 data formats:
1. XML
2. JSON
3. Protocol Buffers
The transport can be either HTTP, HTTPS or TCP. The APIs support xml and json data formats. The response is determined based on the Accept HTTP header
For XML data format, use Accept: application/xml and for JSON data format, use Accept: application/json
All Notification Event API request need an Authorization header. See Authentication for more details.
/api/contextaware/v1/notifications/{name}
Parameters
Returns the Notification Event associated with the specified name and subscribed by the requesting user.
Accepts
Deletes the Notification Event associated with the specified name.
Accepts
/api/contextaware/v1/notifications
Method: GET
Returns all the Notifications Events subscribed by the requesting user.
Accepts
Creates the Notification Event associated with the specified name and subscribed by the requesting user.
Accepts
Schema
1. Absence Event -- Triggers a notification if subscribed devices is absent for the configured absent interval.
2. Battery Event -- Triggers a notification if the battery level of a RFID tag is at the configured level.
3. Exciter Event -- Triggers a notification if the RFID Tag is detected by a configured Exciter.
4. Containment Event -- Triggers a notification if a device is inside or outside of a configured zone.
5. Emergency Event -- Triggers a notification if the Emergency or Panic button on the RFID Tag is pressed.
6. MapInfoChange Event -- Triggers a notification if the Map configuration on MSE changes.
7. Movement Event -- Triggers a notification if a device moves more than a configured distance from its old location or a configured Marker.
8. Presence Event -- Triggers a notification when a device is first detected by the MSE.
9. Streaming Notifications -- Triggers a stream of notification for every location calculation
The above notifications can be configured for a specific macaddress, a list of mac address and with wildcard for a specific device Type.
The Notification Events can be configured to be sent in one of the following 3 data formats:
1. XML
2. JSON
3. Protocol Buffers
The transport can be either HTTP, HTTPS or TCP. The APIs support xml and json data formats. The response is determined based on the Accept HTTP header
For XML data format, use Accept: application/xml and for JSON data format, use Accept: application/json
All Notification Event API request need an Authorization header. See Authentication for more details.
/api/contextaware/v1/notifications/{name}
Parameters
- name The name of the Notification Event subscribed.
Returns the Notification Event associated with the specified name and subscribed by the requesting user.
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 If there is no Notification Event associated with the specified name or the requesting user did not create the notification event.
- 500 Server Error
Deletes the Notification Event associated with the specified name.
Accepts
- application/json
- application/xml
/api/contextaware/v1/notifications
Method: GET
Returns all the Notifications Events subscribed by the requesting user.
Accepts
- application/json
- application/xml
- 200 Successful response
- 404 If there are no Notification Events subscribed by the requesting user.
- 500 Server Error
Creates the Notification Event associated with the specified name and subscribed by the requesting user.
Accepts
Schema
- application/json
- application/xml
- 201 Notification Event was successfully created
- 400 If there is no Notification Event associated with the specified name or the requesting user did not create the notification event.
- 500 Server Error