The document provides a comprehensive guide on designing and developing REST APIs using OpenAPI, Swagger, and Node.js. It explains the importance of CRUD operations, the application of different protocols beyond HTTP, and the necessity of documentation for APIs, particularly through tools like Swagger. Additionally, it outlines the integration with Oracle Cloud services and the utility of Swagger tools for generating client/server code and interactive documentation.

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