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
