0% found this document useful (0 votes)
17 views

Session 4 - REST API Design, Development & Management _ API Specification

Uploaded by

72 Yash Shinde
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
17 views

Session 4 - REST API Design, Development & Management _ API Specification

Uploaded by

72 Yash Shinde
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 52

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

You might also like