In this presentation I will explore what Swagger and OpenAPI is and what advantages you get in developing a REST API for IoT

1. Design & Develop a REST API
with OpenAPI, Swagger, NodeJS
Luigi Saetta
Oracle Cloud Architect
1

2. REST API
• Everything is modeled as a RESOURCE
• Every resource is uniquely identified by a URI
• For example:
• /floor1/devices/dev1
• /floor1/lights/light1
• First of all, you want CRUD for RESOURCES (Create, Read, Update…)
• You use HTTP verbs to define the operations on resources
• GET: read the state
• POST: create a resource
• PUT: update the resource
• DELETE: the resource
2

3. Protocols
• Normally, a REST API is based on HTTP/HTTPS
• But, for example in the IoT World, you can have other protocols
• For example
• CoAP: Constrained Application Protocol, that is modeled after REST, but is a
binary (non Text) protocol based on UDP (not TCP as HTTP)
• In the constrained world of IoT devices HTTP is not always the best choice, is
too much verbose (bandwidth) and requires CPU (i.e.: battery power)
3

4. Discover and Describe an API
• Today, the emerging way for developing Systems and Applications is
MICROSERVICES
• An evolution of SOA
• You can develop the most beautiful API, but then you need to
document it for developers (of the clients)… and no-one wants to
write docs
• In SOA World Services were described using WSDL: a machine
readable language
• You were able to find endpoint for services and operations
• You were able to understand input parameters and response format
• You were able to generate clients with tools
4

5. Discover and Describe an API (2)
• Now, the most common way for an API is REST
• Over HTTP, usually the serialization format is JSON
• But, we still need a way to describe, document an API
• Maybe a way easier than WSDL and XML schema
• We need a way to discover what services are available, what
operations and what format for input and output
• Here, Swagger comes !
5

6. Swagger 101
• The idea is to describe a REST API in a Human and Machine Readable
Format
• You describe your API with a single file
• You can choose YAML
• You can use JSON
• The specification has been defined in a way that it is easy to develop
Open Source tools (and commercial tools)
• To parse Swagger descriptions
• To create server and client scaffold’s code from documentation
• To automatically generate documentation from code
• To generate a UI where you can access documentation and test API
6

7. Example of Swagger
2.0 documentation
for a REST API
7

8. OpenAPI
• Swagger 2.0 has been donated and has become Open API
• “Open API Initiative is focused on creating, evolving and promoting a
vendor neutral API Description Format based on the Swagger
Specification”
• https://www.openapis.org/
• The latest version of the spec can be found on GitHUB
• https://github.com/OAI/OpenAPI-Specification
8

9. Swagger Tools
9

10. Swagger Framework
• You can edit your swagger documentation file using Swagger Editor
• You can use the online version:
• http://editor.swagger.io/#/
• Or download it
• From the editor you can
• Generate server code
• Generate client code
10

11. Swagger UI
• It allows you to easily interact with your API
• It is auto-magically generated from your Swagger spec
• It enables you to see the operations available and to test it
11

12. Swagger and NodeJS
12

13. Swagger in NodeJS
• To install swagger tools and modules for Node
• npm install -g swagger
• To create the starting skeleton for a project
• swagger project create homeauto
• cd homeauto
• To start executing the API
• swagger project start
• To start editing the SWAGGER Yaml (in your browser)
• swagger project edit
13

14. Swagger Editor
14

15. API, swagger and IoT
15

16. API and IoT
• Scenario: a Home/Building Automation solution
• You need an Hub/Gateway, or a set of them
• Protocol translation (ZigBee, ZWAVE, Bluetooth)
• Message Broker (MQTT)
• Field Gateway towards IoT Cloud Service
• If you want to access from some applications functionalities and data
on the gateway you need a REST API
• I’m currently investigating the advantages of using Swagger to design
and develop the REST API
16

17. Swagger and Oracle
• Oracle API Catalog Cloud Service contains a list of API offered by SaaS
and PaaS services
• It can be freely accessed (no fee)
• For each API you can access the Swagger spec (in JSON)
• https://apicatalog.oraclecloud.com/ui/
• You can run NodeJS and swagger tools inside a Docker Container in
Oracle Container Cloud Service
17