1

Design & Develop a REST API with OpenAPI,

Swagger, NodeJSLuigi Saetta

Oracle Cloud Architect

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

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)

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

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 !

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

7

Example of Swagger 2.0 documentation for a REST API

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

9

Swagger Tools

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

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

12

Swagger and NodeJS

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

14

Swagger Editor

15

API, swagger and IoT

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

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