Standardized service interface for Southbound communications in smart cities
Internet of Things is a fast-developing field and in the coming years, it is set to transform the way cities operate. A smart city is an urban area that uses different types of IoT sensors to collect data and then gain insights from it to manage assets and resources efficiently. Most smart city deployments are undertaken by private players at the behest of the government, thus their API interfaces and other communication interfaces may not necessarily be compatible with other cities, thus leading to silos. The India Urban Data Exchange (IUDX) is an open platform that aims to provide a standard interface for data exchange between providers and consumers. IUDX standardizes the interfaces for data discovery, authentication, authorization and data exchange thus enabling interoperability between entities which are IUDX compliant. A smart city can have a wide variety of devices, ranging from raw sensors (like Air Quality Monitors) to complete solutions that enable smart mobility, water management etc. One such variety is the set of devices that are meant for public use, e.g. variable messaging systems, public announcement systems etc. Access to these devices involves downlink (or southbound) communications that are protocol specific. Hence, a high-level layer is needed to operate and manage these devices. This high-level layer is not exposed to public use in most smart-city deployments. One aspect of IUDX is the Service interface which aims to standardize this high-level API layer that is used for southbound communications. This project mainly focuses on designing and developing this interface that can be used for encapsulating downlink operations and management tasks into high-level REST API calls to facilitate easy access and operation of such devices.
Keywords: IUDX, Service APIs, standardization, HTTP methods
|IoT||Internet of Things|
|API||Application Programming Interface|
|REST||Representational State Transfer|
|IUDX||Indian Urban Data Exchange|
|HTTP||Hypertext Transfer Protocol|
|HTTPS||Hypertext Transfer Protocol Secure|
|SOAP||Simple Object Access Protocol|
|XML||eXtensible Markup Language|
|YAML||YAML Ain't Markup Language|
The Ministry of Housing and Urban Affairs has launched an innovative project named Indian Urban Data Exchange (IUDX) for the development of Smart Cities across India. The goal of IUDX is to enable higher operational efficiency in city administration by facilitating data exchange between various civic bodies, municipal departments, application developers and so on. Thus, paving way to gain profound insights into data which can behave as a feedback loop to improve the overall functioning of the city.  The citizens would have apps to access the public data. Authorized users would have access to the services offered by the resources deployed in the smart city.
Each smart city administrator chooses its own system integrators, hardware and software vendors, and application developers that best meet its needs. Within each of the cities, the community will profit through the accessibility of better, more innovative and less expensive applications. The cities themselves will benefit by the decreased development cost and quicker development times enabled by a standard platform, together with the capacity to pick sellers uninhibitedly and keep away from vendor lock-in. Thus IUDX will be an open source software platform that will ensure secure, verified and managed exchange of data amongst various data platforms, third-party authenticated and authorized applications and other data sources, data producers and consumers, both within a city to begin with and scaled up across cities eventually at a national level in a uniform way. 
IUDX consists of set of services that enables access to data resources from one or more hosting resource servers. IUDX is divided into following subsystems:
Catalog server: A catalog server hosts different types of meta-information for the data resources in IUDX.
Authorization server: An authorisation server provides identities to users in the form of certificates. It also handles consent management for non-public data
Resource Server: A resource server serves resources to authorized Apps/Consumers.
Service API: It is a standardized interface that allows unified access to devices which are meant for public use. The service API provides a set of APIs that allows users to use the services offered by the providers with relative ease. Specifically, the service API deals with the physical resources and services in the smart city.
Statement of the Problem
A smart city consists of variety of different types of devices. Every device has its own different features and functionalities. The set of APIs used to control one kind of device may not be able to control device of a different type. Thus for controlling each type of device, a different set of APIs is needed. This makes things very difficult for an app developer. To achieve ease of use in operating these devices, a set of endpoints that is common to all the devices is needed. There exist APIs for individual devices but there was no common set of APIs that can be used to govern multiple devices.
There are some devices which are administrator controlled i.e they are operated by only one person and some devices which are publicly controlled i.e they can be operated by a large number of users. For publicly usable devices it is very likely to have a situation where more than one user would want to use the same device at the same time. Such situation can be addressed by introducing the concept of reservation and priority to avoid conflict of usage among the users.
For instance, consider that there was an emergency and all VMS systems in a city, possibly involving many vendors, needed to be used at once. Without a standard interface and procedure to get access to those devices, it would take a lot of time and effort to carry out the task. In such a situation the service APIs would come in handy. Using the service APIs, all the devices can be grouped together and be accessed through common endpoint using POST request. Thus the service API aims at providing a solution to all these problems through a standard set of APIs.
The major objective of the project is to standardize the set of APIs used for southbound communications. This set of APIs can also be used by administrators looking to control their devices, so that compliance becomes easy when they add some features that are meant for general usage. The main focus is to simplify the protocol used for operating devices so that consumers can use the devices after proper authorization. It also aims at developing a reference implementation of the write APIs and testing them on a device.
The schematic of app consuming service via Service API is shown in Fig 1.
The scope of IUDX is very vast but the aim of service APIs is specifically to standardize the write interface to devices available for public use. The project mainly focuses on developing standard APIs that can be used for controlling publicly usable devices like variable messaging systems, public announcement systems through common APIs. These APIs can be used to perform read as well as write operations on the devices. These APIs would provide a standard for developing any such API that aims at writing data to the devices. This project also provides an implementation of the APIs that can be used as reference by different vendors for developing device APIs.
A smart city consists of diversity of devices and every device has its own features and functionality. There are different set of APIs to control these distinct devices with their varied features. To operate all these devices through a common set of APIs, a set of verbs is needed that covers most of the features of these devices. The first step in designing the common APIs was to find the common features of different devices. Various devices made by different vendors were taken into consideration and a comparison was made to determine the set of API verbs that would be sufficient to carry out the basic functionality of all the devices. The APIs of various display systems like railway display system, airport display system, variable message system, smart TVs; public announcement system, smart media players and digital signage platforms were thoroughly studied for their similarities and differences. The common APIs in most of the devices were:
Read API - for reading the content of the device.
Write API - for writing any content to the device.
Status API - for knowing the current status of the device.
Reservation API - for reserving the devices for different users at different time intervals.
The biggest challenge was to select such verbs that are not only relevant to the feature performed by the devices but also do not cause any ambiguity to the user. The API verbs thus selected convey the intended meaning to the user and cover all the basic functionalities of the devices.
The list of API verbs are represented in figure 2.
GET - Requests a specific representation of a resource.
PUT - Creates or updates a resource with the supplied representation.
POST - Submits data to be processed by the identified resource.
DELETE - Deletes the specified resource.
The endpoints of the devices would be common, the difference would be in the parameters sent in the body of POST request. The service APIs would communicate with the resource server through HTTPS requests made by the clients and pass the necessary data or information from client’s machine to the server, Resource servers would then relay the messages to the devices, in the format and protocol as required by them. The endpoints are selected such that they do not cause any ambiguity to the user. For instance, the user can write data to the device and configure the device using the endpoints write and configurations respectively. If a device is likely to be used by multiple users then a user can even reserve the device for a particular time duration using the reservations endpoint. Proper care has been taken that a user operates only on his own resources and does not manipulate some other user's resources.
A person seeking to utilize either services or data from the smart city is called a consumer. A person who provides the data to be used by other people is called a provider. Consumers can be the citizens of the city that wish to use the devices and providers can be the owners of the devices that are put for public use. The resource provider posts the meta information about the offered service into the IUDX catalog server after appropriate authorization. The catalog service allows the authorized users to search for available service and retrieve information about the offered service, as meta information. The user can use this meta information to make requests to the resource server to avail the services offered by the resource after proper authentication.
After many discussions with different vendors, a common set of API verbs was reached that covered most of the basic features of different types of devices. The API document can be viewed on the following link.("Service API")  This document contains the list of APIs along with their description, request body and example.
The architecture diagram of Service API is shown in Fig 3.
A reference implementation of the APIs has been developed in Flask which is a micro web framework ("Flask")  written in Python , with PostgreSQL database. The code of the APIs can be found on the following github link. ("service_apis")  The PostgreSQL database consists of following tables:
devices - It contains list of devices.
users - It contanis information about the users.
groups - It contains list of groups made by users.
reservations - It contains information regarding the reservation time.
reservations_info - It contains reservation information.
device_state - It contains information about devices in a reservation.
configure - It contains the device configurations.
write_op - It contains the device content.
These tables store all the necessary information for the smooth functioning of the APIs. The requests are made by the user to the flask server using HTTPS protocol. The authenticity of the information provided in request body and headers are checked, appropriate actions are performed and corresponding messages are displayed to the user. Thus the reference implementation performs the functionality of the Service API.
Use cases for workflow of resources
Following are two use cases that represent two different workflows to use the services offered by the resources. The first use case represents the workflow for administrator controlled resources i.e the resources which are controlled by one set of users who are the administrators. The second use case represents the workflow for publicly usable resources i.e the public resources which can be used by multiple users. In the following use cases it is assumed that all operations are performed after proper authorization and authentication.
Workflow for administrator controlled resources
- The user creates a group of all the devices or resources to operate on using /groups endpoint with HTTP POST method by providing the device-ids of the devices to group together, in the request body.
- If the user wishes to update the group, it can be done using
/groups/<gid> endpoint with HTTP PUT and providing the updated resources in the request body.If the user wishes to delete the group, it can be done using /groups/<gid> endpoint with HTTP DELETE method.
- At the time of group creation, the user can specify the name of the group in the request body otherwise the resource server creates a group-id itself and returns it to the user.
- After the group is created, the user can configure the devices of a group according to the requirements using POST /configurations endpoint and providing the configuration parameters and the group-id or device-id in the request body.
- If the user wishes to update the configurations, it can be done using /configurations endpoint with HTTP PUT method and providing the group-id or device-id in the request body along with the updated configuration parameters. If the user wishes to delete the configurations, it can be done using /configurations endpoint with HTTP DELETE method and providing the group-id or device-id in the request body.
- The user can write any data to the device by using POST /write endpoint and providing the group-id or device-id in the request body along with the data to be written on the device.
- If the user wants to change the data, it can be done using the /write endpoint with HTTP PUT and providing the group-id or device-id in the request body along with the updated data. If the user wants to delete the data, it can be done using the /write endpoint with HTTP DELETE method and providing the group-id or device-id in the request body.
Workflow for publicly usable resources
- The user creates a group of all the devices or resources to operate on using /groups endpoint with HTTP POST method by providing the device-ids of the devices to group together, in the request body.
- If the user wishes to update the group, it can be done using /groups/<gid> endpoint with HTTP PUT and providing the updated resources in the request body. If the user wishes to delete the group, it can be done using /groups/
<gid> endpoint with HTTP DELETE method.
- After the group is created, the user can reserve the resources of the group for a particular time duration using /reservations endpoint with HTTP POST method and providing the reservation start-time and reservation end-time in the request body along with the group-id or device-id. If the resources are not reserved by any other user during that time duration, the Resource Server returns a rid (reservation-id) using which the user can perform further operations on the resources. If the resources are already reserved during that time duration, the Resource Server informs the user that the resources are already reserved.
- A reservation can be updated by the user using /reservations/<rid> endpoint with HTTP PUT method specifying the updated reservation start-time and reservation end-time in the request body. A reservation can be deleted by the user using /reservations/<rid>
endpoint with HTTPDELETE method.
- Once the reservation is made and the reservation time starts, the user can operate on the resources by seeking permission from the Resource Server by posting a request at /open/channel endpoint along with the reservation-id in the request body. If no high priority task is running on the resources, the Resource Server grants the user the permission to operate on the resources through a channel-id. The user can use this channel-id to configure the resources or write on the resources. If any high priority task is running on the resources, the Resource Server asks the user to try after sometime.
- Once the channel is opened and channel-id is obtained by the user, the user can suspend the channel using suspend/channel endpoint, resume the channel using resume/channel endpoint or close the channel using close/channel endpoint, by specifying the channel-id in the request body.
- After the channel is opened, the user can configure the devices according to the requirements using POST /configurations endpoint and providing the configuration parameters and the group-id or device-id along with the reservation-id or channel-id in the request body.
- Later if the user wants to change the configurations, it can be done using /configurations endpoint with HTTP PUT method and providing the group-id or device-id and updated configuration parameters in the request body along with reservation-id or channel-id. If the user wishes to delete the configurations, it can be done using /configurations endpoint with HTTP DELETE method and providing the group-id or device-id in the request body along with reservation-id or channel-id.
- The user can write any data to the device by using POST /write endpoint and specifying the group-id or device-id and the data to be written on the device in the request body along with reservation-id or channel-id.
- Later if the user wants to change the data, it can be done using /write endpoint with HTTP PUT method and providing the group-id or device-id and updated data parameters in the request body along with reservation-id or channel-id. If the user wishes to delete the data, it can be done using /write endpoint with HTTP DELETE method and providing the group-id or device-id in the request body along with reservation-id or channel-id.
- After the user has finished operating the resources, the user may close the channel through /close/channel endpoint by providing the reservation-id or channel-id in the request body otherwise the channel will automatically be closed by the Resource Server when the reservation time ends.
After designing and developing the Service interface layer, a reference implementation was built and tested. This implementation was tested on a live Streetlight Management System and it was able to capture all the functionalities of the system successfully. Furthermore, the interface was reviewed and accepted by participating companies in IUDX group. It was also reviewed by a VMS company, Pickcel , which gave positive feedback about the features of the interface.
CONCLUSION AND FUTURE SCOPE
The Service interface was designed after reviewing the APIs of various digital signage systems, smart TVs, media players, announcement systems etc. They were also tested out on a live system which yielded positive results. In order to better understand the benefits and possible shortcomings of the system, the Service interface needs to be deployed on a city-wide scale consisting of various device types and use-case scenarios. Furthermore, the interface needs to include more device-specific features so that its inclusiveness is enhanced.
- RESTful API. https://www.mulesoft.com/resources/api/restful-api
- HTTP Methods. https://restfulapi.net/http-methods/
- Service API. https://docs.google.com/document/d/1BCaWlkWpkUXMLD1ygu3fm5EfUNDo tk9zpbF8Nd0T5ZQ /edit#heading=h.cr41vnrke1qb
- Flask. https://pymbook.readthedocs.io/en/latest/flask.html
- service_apis. https://github.com/rbccps-iisc/service_apis
- Pickcel. https://www.pickcel.com/
I express my sincere gratitude to Professor Bharadwaj Amrutur for his guidance and patience, and giving me a project in the area of my interest. I am thankful to him for making this project a great learning experience for me.
I am thankful to Mr. Poorna Chandra Tejasvi for his constant guidance and support throughout this project.
I would also like to thank Mr. Chetan Kumar, Mr. S.V.R. Anand and and each member of the IUDX team for all the support and discussions.
I am indebted to Indian Academy of Sciences for providing me this wonderful oppurtunity.
I would like to thank Indian Institute of Science for providing me a platform to learn something new and innovative.