rest api with swagger and nodejs
TRANSCRIPT
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