REST API Design, Development &

Management

Session 4: API Specification

Recap of API Design
Assignment Review
Q&A

REST API Design, Development & Management

Let’s see an example of statelessness
property of REST constraint.

REST API Design, Development & Management

Session 4: API Specification
Open API Specification

How to structure the specification document

REST API Design, Development & Management

Open API Specification

REST API Design, Development & Management

 Application Programming Interface

A user interface of data and systems that is consumed by applications

rather than humans
A well defined contract between the API provider and consumer

REST API Design, Development & Management

 Specifications

Analysis

App Developer API Developer

Requirements
Specifications

Mocking
&
Validations

REST API Design, Development & Management

API Specification Standards

API Blueprint from Apiary

RAML from Mulesoft (now supports
openAPI)
OpenAPI is an open standard
(Formerly known as swagger)

REST API Design, Development & Management

Swagger

The de-facto standard by multiple vendors

Vibrant community
https://github.com/swagger-api

REST API Design, Development & Management

Benefits of Swagger specification
Developer Documentation

Automated Proxy Creation

Server Code Generation

Client Code Generation

Server Virtualization (mocking)

REST API Design, Development & Management

All but one is a REST
Specification standard

ⓘ Start presenting to display the poll results on this slide.

_______ is the most
commonly accepted REST
API Specifications standard

ⓘ Start presenting to display the poll results on this slide.

Contract first approach refers to
the process of first creating the
_____________

ⓘ Start presenting to display the poll results on this slide.

It is suggested that API be created in a
___________ manner by the API developer
and the API consumer

ⓘ Start presenting to display the poll results on this slide.

Swagger tools allow specs
to be used for generation of

ⓘ Start presenting to display the poll results on this slide.

Open API Specification

Open API Initiative (OAI) is focused on

creating evolving and promoting a vendor of
neutral API Description Format based on
Swagger specification.

JSON YAML

REST API Design, Development & Management

Why YAML?
● YAML is meant for human consumption, i.e
easily readable & understandable
YAML
● Data serialization language like XML, JSON
○ Mostly used for config files
http://yaml.org
● Superset of JSON
○ Uses indentation instead of symbols
such as <> or {}
● Online editor
○ https://editor.swagger.io/

REST API Design, Development & Management

Swagger/OAI specs are
written in ______

ⓘ Start presenting to display the poll results on this slide.

Which statement is True

ⓘ Start presenting to display the poll results on this slide.

Instead of using characters
like { } YAML uses

ⓘ Start presenting to display the poll results on this slide.

OAI Stands for
_______________

ⓘ Start presenting to display the poll results on this slide.

YAML is meant for
_____________

ⓘ Start presenting to display the poll results on this slide.

How to structure API specification?

REST API Design, Development & Management

Open API (Swagger) Document Structure
Metadata Root Document

External Doc. Tags

Definitions

definitions parameters securityDefinitions

$ref
paths
$ref

REST API Design, Development & Management

Open API (Swagger) Metadata

Info

Contact License
● version
● title ● name ● name
● description ● url ● url
● email

REST API Design, Development & Management

Open API (Swagger) Root Document

Root Document

● host api.domain.com:3000
● basePath v1
● schemes[:string] http, https
● consumes[string]
application/json, application/xml
● produces[string]

REST API Design, Development & Management

Open API (Swagger) Tags

tags[]

Tag # 1 Tag # 2

● name ● name
● description ● description

● Metadata - used by developers portal tools

● Referred in Paths/Operations

REST API Design, Development & Management

Open API (Swagger) externalDocs

externalDocs

● description
● url

● Link to document repository. Ex. Link to FAQ page or T&C page

REST API Design, Development & Management

All common schemas are
defined under the
___________

ⓘ Start presenting to display the poll results on this slide.

The version for the
resource/path is created by
using the element __________

ⓘ Start presenting to display the poll results on this slide.

The specification may linked with
detailed document on a website by using
the element _________

ⓘ Start presenting to display the poll results on this slide.

To make the specifications
searchable and filterable, it is
suggested to use __________

ⓘ Start presenting to display the poll results on this slide.

The part of URL between the host:port and
resource is referred to in the
specifications as the __________

ⓘ Start presenting to display the poll results on this slide.

 Open API (Swagger) Definitions
Security schema:
security: from the operation

Definitions

definitions parameters securityDefinitions

Request/Response schema: Request/Input schema:

$ref: “#/definitions” from operation $ref: “#/parameters” from operation

REST API Design, Development & Management

Open API (Swagger) definitions
● Common schema Request Response

definitions

Request/Response #1 Request/Response #1

schema schema

examples examples

JSON schema Mime-type: {

Example as
per schema
REST API Design, Development & Management
}
Open API (Swagger) Parameters
parameters

parameter #1 parameter #1

● name ● name
● description ● description
schema schema
● in ● in
● required ● required

{
body,
query,
Required : in == body header,
path,
formData
} REST API Design, Development & Management
Open API (Swagger) Parameter naming

Body No name needed

Query https://mybank.com/api/v1/accounts?status=active

Path https://mybank.com/api/v1/accounts/{id}

Header Custom header name

REST API Design, Development & Management

 Open API (Swagger) SecurityDefinitions

{basic, apiKey, oauth2}

securityDefinitions
Used for associating
● type with operation
● name
● description
● in
{Query, header}

REST API Design, Development & Management

Schema for response cannot
be used unless it is defined
under the definitions

ⓘ Start presenting to display the poll results on this slide.

The definitions are
referenced by using the json
________ operator

ⓘ Start presenting to display the poll results on this slide.

The definitions may be placed in a
different files and linked to paths/operator
by way of $ref with absolute path

ⓘ Start presenting to display the poll results on this slide.

A request/response schema is a MUST
under definitions before a Path/Operation
can be created in the specifications.

ⓘ Start presenting to display the poll results on this slide.

Open API (Swagger) paths
● Multiple path definitions
● Each path can have multiple operations

/{path}

get: post: put:

Summary Consumes Parameters

Description Produces Responses

Tags[]
Security
External Documentation

REST API Design, Development & Management

Open API (Swagger) paths -> operation
get: post: put: ...

Summary

Short and long descriptions

Description

Tags[] Pre defined tags

External Documentation Link to external docs

REST API Design, Development & Management

Open API (Swagger) paths -> operation
get: post: put: ...

Summary Consumes
MIME types

Description Produces

Tags[]

External Documentation

REST API Design, Development & Management

Open API (Swagger) paths -> operation
get: post: put: ...

Summary Consumes Parameters $ref: “#/parameters”

Description Produces Responses $ref: “#/parameters”

Tags[] Security Security:

“#/securityDefinitions”

External Documentation

REST API Design, Development & Management

Tags MUST be defined
before they can be used in
the operations

ⓘ Start presenting to display the poll results on this slide.

The Operations security
elements refers to the
securityDefinition by way of
`$ref`

ⓘ Start presenting to display the poll results on this slide.

The operation may have a
externalDocumentation
element

ⓘ Start presenting to display the poll results on this slide.

There can be only one
operation per path

ⓘ Start presenting to display the poll results on this slide.

Assignment for this weekend
● Mini applies for a credit card
● The credit card application have the following attributes: applicant_name*, application_date*, age, salary, status
(approved, rejected)
● On successful application a new credit card account got created (account attributes are: id*, credit_limit*,
available_limit*, account_holder_name*, status* (approved, rejected) ) and a new credit card issued.
● Mini loves to use her new credit card to shop online.
● Every credit card transaction will have the following attributes: transaction_id*, amount*, date*, transaction_type*
(credit, debit), remarks.
● 5th day of every month her statement/bill gets generated. Statement have attributes like: statement_date*,
due_date*, bill_amount*, min_due*.

Your task is to

1. List all the resources this problem statement can have.

2. Create a new API specification document for this problem statement
a. First define all meta information
b. Second, define all resources/Models
c. Third, define paths for CRUD operations of the following: Credit Card Application,
Credit Card Account, Transaction, Credit Card Statement.
i. Every path should contain: summary, description, tags, parameters (if any),
request, responses (200, 401, 404, 422)
REST API Design, Development & Management
 Thank you!

See you on Monday at 10AM

REST API Design, Development & Management