API Introduction and Specifications using SWAGGER

2 min readDec 31, 2019

What is an API?

API stands for Application Programming Interface.
A User interface to data and system that is consumed by applications rather than humans.

REST API frameworks:

There are multiple rest api frameworks on NodeJS. Some of the popular frameworks are Express, Hapi, Restify, StrongLoop.

Types of APIs:

There are 3 type of consumers:

Internal or Private consumers:

The internal consumer is the part of same organization that is the provider of the API

2. Public or External consumers:

The public consumer is outside of the organization that is creating the API or that owns the API.

3. Partner

This consumer has a trusted relationship with the Enterprise of the organization that is creating and exposing the API

Based on the above 3 types of consumers we have 3 types of APIs.
Which are :

•Private API
•Public API
•Partner API

OpenAPI

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including: Available endpoints ( /users ) and operations on each endpoint ( GET /users , POST /users ) Operation parameters Input and output for each operation.

The specification is written in a single file in JSON or YAML format consisting of three sections:

A header with the API name, description, and version, as well as any additional information.
Descriptions of all resources, including identifiers, HTTP methods, all input parameters, response codes, and body data types, with links to definitions.
All definitions that can be used for input or output, in JSON Schema format (which, yes, can also be represented in YAML.)

Now, i am going to use swagger-ui-express npm module , this allows you to serve auto-generated swagger-ui generated API docs from express, based on a swagger.json file

Files Structure :