A REST API for a Smart City


In my previous article on Medium, entitled “A Design-first approach to API implementation”, I showed, with a fair level of detail, how to design a REST API using Oracle Apiary and, then, how to use the interface definition, based on OpenAPI (Swagger 2.0), in order to generate, automatically, the initial “skeleton” for the implementation of the service, based on Python-Flask.

Some details for the implementation..

The data collected by the sensors are stored in an Oracle MySQL database. One of the best choices, also taking into account the results of the last IoT Developer Survey held by the Eclipse Foundation.

From Eclipse Foundation, IoT Developer Survey, 2018
  • each device (box containing a group of sensors) is identified by a numeric "device_id" (id_list)
  • Each record contains a "timestamp" (Unix timestamp, 10 digits)
  • The record contains temporally related measures (theoretically same instant)
  • Read last measure (available, for device #N)
  • Read last M measures (for device #N)

Apiary based approach on Design.

In Apiary, after creating a project, the first important operation to be performed is the definition of the API interface. The tool is the Editor.

  • The name of the project and the version of Swagger (in our case 2.0)
  • A description, useful for documentation
  • The base path (basePath) for URLs
  • The paths (path) for each function and the HTTP (GET ...) verbs allowed
  • (possible) input parameters
  • response format
OpenAPI (Swagger 2.0) interface spec.

“Mock Server” and specification sharing.

In an agile, modern approach, it is advisable to make available the interface specification as soon as it is defined and approved, so that developers, for example for Apps or Chatbot, who need to use it have a certain and authoritative reference point.

  • a Mock Server that can be invoked; It obviously returns the examples defined in the specification
Mock Server
  • Automatic generation of client code, for various languages
Client code generation (here for Python)
swagger-codegen generate -i ./swagger.yaml -l python-flask
requirements.txt for Python modules
pip install -r requirements.txt
python3 -m swagger_server

Some best practices and recommendations.

The code shown is for a prototype that wants to "indicate" how to proceed. It is not entirely suitable for use in a production environment.

  • Use a Connection Pooling: creating connections to the DB is always an "expensive" and "slow" operation, so avoid creating a connection for each request, but use instead a connection pool; The createConnection() function shows this approach
  • Do not insert the credentials for opening the connections in the main Python code, but place them in a separate configuration file (in our case dbconfig.py)
  • Use a MySQL account for data access that has only READ privilege on the tables
  • Flask has its own HTTP server; It is not appropriate to use it in a production environment. You can use NGINX as a Reverse Proxy, or there are other alternatives (WSGI)

Advantages of a Design-First approach, based on Apiary.

In conclusion, we have shown how, starting from existing data produced by sensors and stored in a MySQL database, it is quite easy to create a REST API that exposes and facilitates access to such data.

Next steps.

In this article we have addressed an important topic, security, only in a minimal form.


Almost nothing is born in the desert. This article wouldn’t have been possible without support and suggestions from the manager and all the colleagues of the team I work in: Oracle Italy Innovation Solutions Team. Also, I must say a big thanks to the Partner and all the people from Harpa Italia, who have provided the devices (Aircare) and the core SW infrastructure, hosted for the joint solution in Oracle Cloud Infrastructure. Last but not the least, this work has been developed as part of the effort to build the ProximaCity Demo: a demo of a Smart City. Have a look.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Luigi Saetta

Luigi Saetta

Born in the wonderful city of Naples, but living in Rome. Always curious about new technologies and new things. I work in a big Cloud Company.