SlideShare a Scribd company logo

Designing Practical RESTful APIs

Slides at @trbmeetup https://trbmeetup.doorkeeper.jp/events/73198

1 of 63
Download to read offline
Designing
Practical
RESTful APIs
Who am I?
• Hiroshi Ogino
• web developer
• home-based worker
• founder of @yurufuwarb
Agenda
• What is REST?
• How should we design practical
APIs?
• Conclusion
Agenda
• What is REST?
• How should we design practical
APIs?
• Conclusion
REST
• REpresentational State Transfer
• Architecture style, where data and
functionality are accessed as URIs
• Simple, Lightweight, and Fast
3 Essential points
REST
• Resource-Oriented
• Uniform Interface
• Stateless
Resource-Oriented
• Addressable, Indexable
• Resources are identified as Uniform
Resource Identifiers (URIs)
• Connectedness
• Resources should link together in
their representation
Designing Practical RESTful APIs
The world is filled
with a lot of resources
https://xxx/truck
https://yyy/car
They are Identified
by URI
https://zzz/windmill
REST
• Resource-Oriented
• Uniform Interface
• Stateless
HTTP METHODS
Uniform Resource
Locator (URL)
GET PUT PATCH POST DELETE
Collection
https://api.xxx/items
List details of
the collection
Replace the
entire collection
with another one
Not
generally
used
Create a
new entry
in the
collection
Delete a
entire
collection
Element
https://api.xxx/items/12
Retrieve a
representation
of the member
of the
collection
Replace the
member of the
collection, or
Create it if it
does not exist
Update
the
member of
the
collection
Not
generally
used
Delete
the
member of
the
collection
REST
• Resource-Oriented
• Uniform Interface
• Stateless
Designing Practical RESTful APIs
Hi, for here or to go?
For here.
STATEFUL
What can I get you?
Can I have two cheeseburgers and one
order of fries?
STATEFUL
What size fries would
you like?
Small.
STATEFUL
Would you like
anything to drink?
I’ll have coke.
STATEFUL
Would you like
anything else?
No, I’m good.
STATEFUL
STATEFUL
• Cashier remembers your past orders
• You only have to put your latest order
Hi, for here or to go?
For here.
STATELESS
What can I get you?
For here.
Can I have two cheeseburgers and one
order of fries?
STATELESS
What size fries would
you like?
For here.
Can I have two cheeseburgers and one
order of fries?
Small.
STATELESS
Would you like
anything to drink?
For here.
Can I have two cheeseburgers and one
order of fries?
Small.
I’ll have coke.
STATELESS
STATELESS
• Cashier DOES NOT remember your past orders
• You have to put orders including past orders
STATELESS
• Cashier DOES NOT remember your past orders
• You have to put orders including past orders
What good will come of it? 🤔
STATELESS
• It was said that the main advantage of STATELESS was
SCALABILITY in the past
• It was believed that STATEFUL COULD NOT scale out
STATELESS
• It was said that the main advantage of STATELESS was
SCALABILITY in the past
• It was believed that STATEFUL COULD NOT scale out
• Nowadays …
• LB can dispatch the same server which is scaled out
• scaled out servers can share the same session store
(RDS, Redis, …)
It’s no longer a big deal!
Agenda
• What is REST?
• How should we design practical
APIs?
• Conclusion
PRACTICAL … ?
Practical
• Dictionary says
• involving activity rather than study or theory
• likely to be successful or useful
Practical
SHU-HA-RI is a Japanese martial art
concept, and describes the stage of
learning to mastery
Practical
Repeat the forms and discipline ourselves
to absorb the forms and to find the values
lurking behind them
SHU → obey, protect
Practical
Based on the fundamentals learned with
break the forms and make innovation
HA → detach
,
Practical
Completely depart from the forms, act in
accordance with what we want
RI → leave
Practical
Find the key to PRACTICAL hiding around
here
Practical
• Dictionary says
• involving activity rather than study or theory
• likely to be successful or useful
• MAY NOT OBEY all constraints of the REST architecture style
• BREAK theory now and then for a specific purpose
• FOCUS ON successful / useful
3 Questions
Reaching Practical
Design
Q.1
How should we design
the ENDPOINT to get our own
information?
GET /customers/:id
From GET method, easy to expect retrieving the customer
information from customers table while requesting
Anyone CAN GUESS other’s endpoints
GET /me or /mypage
From GET method, easy to expect retrieving my
information from customers table while requesting
Anyone CAN NOT GUESS other’s endpoints
However, we need to store customer_id in a session to
identify the customer and it makes this endpoint
STATEFUL … is it okay?
🤔
GET /me or /mypage
STATELESS
• It was said that the main advantage of STATELESS was
SCALABILITY in the past
• It was believed that STATEFUL COULD NOT scale out
• Nowadays …
• LB can dispatch the same server which is scaled out
• scaled out servers can share the same session store
(RDS, Redis, …)
It’s no longer a big deal!
REMAINS scalable even if we store customer_id in a
session
Caution: we should not manage long-life objects in a
session because it may deprive the independency of
each request
GET /me or /mypage
Learned from Q.1
• SHOULD NOT allow anyone to guess the
other’s endpoints if the resources of the
endpoint are serious information
• CAN use a session for a specific purpose
Q.2
How should we design
the RESOURCE and the ENDPOINT
that allow customers to agree with
the Terms of Service?
Q.2
How should we design
the RESOURCE and the ENDPOINT
that allow customers to agree with
the Terms of Service?
This resource CAN NOT represent updating Terms of Service
This resource CAN NOT manage enforced datetime
id int
nickname string
:
agreement booleancustomers
ADD agreement column to customers table
This resource CAN represent updating Terms of Service
This resource CAN manage enforced datetime
● enforced date is managed by version column
● enforced datetime is managed by start_at column
CREATE terms / terms_agreement tables
customers
term_agreements
terms
id int
version string
start_at datetime
:
id int
customer_id int
term_id int
:
Q.2
How should we design
the RESOURCE and the ENDPOINT
that allow customers to agree with
the Terms of Service?
:version is enforced date (ex. /terms/20180515/agreements)
clear to agree with which version of terms
From POST method, easy to expect inserting a new term
agreement record while requesting
POST /terms/:version/agreements
Learned from Q.2
• SHOULD maximize representation of a
resource
• SHOULD make an Endpoint semantic
Q.3
How should we design
the SEQUENCE in which customers
buy something in an application?
Back-end ServerCustomer
https://api.example.com/items
Network
(1) SEARCH
Back-end ServerCustomer Network
(2) CONFIRM
Back-end ServerCustomer Network
(3) PURCHASE
https://api.example.com/items/order?
confirm=true
https://api.example.com/items/order
Customer
STORE purchase data
CONFIRM
Network Back-end Server Session Store
COMPLETE confirmation
PURCHASE
VALIDATE purchase data
DELETE purchase data
PROCESS purchase
COMPLETE purchase
-
(2) CONFIRM
-
(3) PURCHASE
Customer
STORE purchase data
CONFIRM
Network Back-end Server Session Store
PURCHASE
VALIDATE purchase data
DELETE purchase data
PROCESS purchase
-
PREVENT
duplicated requests
COMPLETE confirmation
COMPLETE purchase
Learned from Q.3
• SHOULD establish a confirmation phase
to operate significant action, such as a
purchase
• MUST use a session intentionally to
prevent duplicated requests
Agenda
• What is REST?
• How should we design practical
APIs?
• Conclusion
Learned from Q.1
• SHOULD NOT allow anyone to guess the
other’s endpoints if the resources of the
endpoint are serious information
• CAN use a session for a specific purpose
Learned from Q.2
• SHOULD maximize representation of a
resource
• SHOULD make an Endpoint semantic
Learned from Q.3
• SHOULD establish a confirmation phase
to operate significant action, such as a
purchase
• MUST use a session intentionally to
prevent duplicated requests
Thank you

Recommended

Lessons learned on the Azure API Stewardship Journey.pptx
Lessons learned on the Azure API Stewardship Journey.pptxLessons learned on the Azure API Stewardship Journey.pptx
Lessons learned on the Azure API Stewardship Journey.pptxapidays
 
Overview of REST - Raihan Ullah
Overview of REST - Raihan UllahOverview of REST - Raihan Ullah
Overview of REST - Raihan UllahCefalo
 
Recipes for API Ninjas
Recipes for API NinjasRecipes for API Ninjas
Recipes for API NinjasNordic APIs
 
Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, ...
Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, ...Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, ...
Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, ...Tom Hofte
 
Why do they call it Linked Data when they want to say...?
Why do they call it Linked Data when they want to say...?Why do they call it Linked Data when they want to say...?
Why do they call it Linked Data when they want to say...?Oscar Corcho
 
Using Redis Streams To Build Event Driven Microservices And User Interface In...
Using Redis Streams To Build Event Driven Microservices And User Interface In...Using Redis Streams To Build Event Driven Microservices And User Interface In...
Using Redis Streams To Build Event Driven Microservices And User Interface In...Redis Labs
 
Rest api best practices – comprehensive handbook
Rest api best practices – comprehensive handbookRest api best practices – comprehensive handbook
Rest api best practices – comprehensive handbookKaty Slemon
 

More Related Content

Similar to Designing Practical RESTful APIs

Building the Eventbrite API Ecosystem
Building the Eventbrite API EcosystemBuilding the Eventbrite API Ecosystem
Building the Eventbrite API EcosystemMitch Colleran
 
REST-API's for architects and managers
REST-API's for architects and managersREST-API's for architects and managers
REST-API's for architects and managersPatrick Savalle
 
Restful web-services
Restful web-servicesRestful web-services
Restful web-servicesrporwal
 
Web Services
Web ServicesWeb Services
Web ServicesKrish
 
Chris Mathias Presents Advanced API Design Considerations at LA CTO Forum
Chris Mathias Presents Advanced API Design Considerations at LA CTO ForumChris Mathias Presents Advanced API Design Considerations at LA CTO Forum
Chris Mathias Presents Advanced API Design Considerations at LA CTO ForumChris Mathias
 
Creating Sustainable Website Processes
Creating Sustainable Website ProcessesCreating Sustainable Website Processes
Creating Sustainable Website ProcessesNatalie Semczuk
 
Алексей Веркеенко "Symfony2 & REST API"
Алексей Веркеенко "Symfony2 & REST API" Алексей Веркеенко "Symfony2 & REST API"
Алексей Веркеенко "Symfony2 & REST API" Fwdays
 
Together Cheerfully to Walk with Hypermedia
Together Cheerfully to Walk with HypermediaTogether Cheerfully to Walk with Hypermedia
Together Cheerfully to Walk with HypermediaVladimir Tsukur
 
Design API using RAML - basics
Design API using RAML - basicsDesign API using RAML - basics
Design API using RAML - basicskunal vishe
 
Making Sense of Hypermedia APIs – Hype or Reality?
Making Sense of Hypermedia APIs – Hype or Reality?Making Sense of Hypermedia APIs – Hype or Reality?
Making Sense of Hypermedia APIs – Hype or Reality?Akana
 
JOSA TechTalks - RESTful API Concepts and Best Practices
JOSA TechTalks - RESTful API Concepts and Best PracticesJOSA TechTalks - RESTful API Concepts and Best Practices
JOSA TechTalks - RESTful API Concepts and Best PracticesJordan Open Source Association
 
Business Applications Integration In The Cloud
Business Applications Integration In The CloudBusiness Applications Integration In The Cloud
Business Applications Integration In The CloudAnna Brzezińska
 
Pragmatic REST APIs
Pragmatic REST APIsPragmatic REST APIs
Pragmatic REST APIsamesar0
 
DataHero / Eventbrite - API Best Practices
DataHero / Eventbrite - API Best PracticesDataHero / Eventbrite - API Best Practices
DataHero / Eventbrite - API Best PracticesJeff Zabel
 
Designing your API Server for mobile apps
Designing your API Server for mobile appsDesigning your API Server for mobile apps
Designing your API Server for mobile appsMugunth Kumar
 

Similar to Designing Practical RESTful APIs (20)

Building the Eventbrite API Ecosystem
Building the Eventbrite API EcosystemBuilding the Eventbrite API Ecosystem
Building the Eventbrite API Ecosystem
 
Enterprise REST
Enterprise RESTEnterprise REST
Enterprise REST
 
REST-API's for architects and managers
REST-API's for architects and managersREST-API's for architects and managers
REST-API's for architects and managers
 
Restful web-services
Restful web-servicesRestful web-services
Restful web-services
 
Consumer-centric API Design
Consumer-centric API DesignConsumer-centric API Design
Consumer-centric API Design
 
Web Services
Web ServicesWeb Services
Web Services
 
Chris Mathias Presents Advanced API Design Considerations at LA CTO Forum
Chris Mathias Presents Advanced API Design Considerations at LA CTO ForumChris Mathias Presents Advanced API Design Considerations at LA CTO Forum
Chris Mathias Presents Advanced API Design Considerations at LA CTO Forum
 
Creating Sustainable Website Processes
Creating Sustainable Website ProcessesCreating Sustainable Website Processes
Creating Sustainable Website Processes
 
Алексей Веркеенко "Symfony2 & REST API"
Алексей Веркеенко "Symfony2 & REST API" Алексей Веркеенко "Symfony2 & REST API"
Алексей Веркеенко "Symfony2 & REST API"
 
Together Cheerfully to Walk with Hypermedia
Together Cheerfully to Walk with HypermediaTogether Cheerfully to Walk with Hypermedia
Together Cheerfully to Walk with Hypermedia
 
Design API using RAML - basics
Design API using RAML - basicsDesign API using RAML - basics
Design API using RAML - basics
 
Cqrs api
Cqrs apiCqrs api
Cqrs api
 
Making Sense of Hypermedia APIs – Hype or Reality?
Making Sense of Hypermedia APIs – Hype or Reality?Making Sense of Hypermedia APIs – Hype or Reality?
Making Sense of Hypermedia APIs – Hype or Reality?
 
JOSA TechTalks - RESTful API Concepts and Best Practices
JOSA TechTalks - RESTful API Concepts and Best PracticesJOSA TechTalks - RESTful API Concepts and Best Practices
JOSA TechTalks - RESTful API Concepts and Best Practices
 
Rest APIs Training
Rest APIs TrainingRest APIs Training
Rest APIs Training
 
Business Applications Integration In The Cloud
Business Applications Integration In The CloudBusiness Applications Integration In The Cloud
Business Applications Integration In The Cloud
 
Pragmatic REST APIs
Pragmatic REST APIsPragmatic REST APIs
Pragmatic REST APIs
 
REST and RESTful Services
REST and RESTful ServicesREST and RESTful Services
REST and RESTful Services
 
DataHero / Eventbrite - API Best Practices
DataHero / Eventbrite - API Best PracticesDataHero / Eventbrite - API Best Practices
DataHero / Eventbrite - API Best Practices
 
Designing your API Server for mobile apps
Designing your API Server for mobile appsDesigning your API Server for mobile apps
Designing your API Server for mobile apps
 

More from Hiroshi Ogino

ハートレイルズ流リモートワークのご紹介
ハートレイルズ流リモートワークのご紹介ハートレイルズ流リモートワークのご紹介
ハートレイルズ流リモートワークのご紹介Hiroshi Ogino
 
レッツゴーゆるふわ.Rb
レッツゴーゆるふわ.Rbレッツゴーゆるふわ.Rb
レッツゴーゆるふわ.RbHiroshi Ogino
 
今すぐAWSが使いたくなる話
今すぐAWSが使いたくなる話今すぐAWSが使いたくなる話
今すぐAWSが使いたくなる話Hiroshi Ogino
 
"地方エンジニア" という考え方はすでに終わっている
"地方エンジニア" という考え方はすでに終わっている"地方エンジニア" という考え方はすでに終わっている
"地方エンジニア" という考え方はすでに終わっているHiroshi Ogino
 
信頼される仕事
信頼される仕事信頼される仕事
信頼される仕事Hiroshi Ogino
 
ビジネスモデルキャンバス素振り会
ビジネスモデルキャンバス素振り会ビジネスモデルキャンバス素振り会
ビジネスモデルキャンバス素振り会Hiroshi Ogino
 
Agile japan 2013 四国サテライト(LT)
Agile japan 2013 四国サテライト(LT)Agile japan 2013 四国サテライト(LT)
Agile japan 2013 四国サテライト(LT)Hiroshi Ogino
 
「正しいアジャイル」でなくてもいい
「正しいアジャイル」でなくてもいい「正しいアジャイル」でなくてもいい
「正しいアジャイル」でなくてもいいHiroshi Ogino
 
仲間になろう!~ We are the World ~
仲間になろう!~ We are the World ~仲間になろう!~ We are the World ~
仲間になろう!~ We are the World ~Hiroshi Ogino
 
エンジニアがとるべき8つの行動
エンジニアがとるべき8つの行動エンジニアがとるべき8つの行動
エンジニアがとるべき8つの行動Hiroshi Ogino
 

More from Hiroshi Ogino (10)

ハートレイルズ流リモートワークのご紹介
ハートレイルズ流リモートワークのご紹介ハートレイルズ流リモートワークのご紹介
ハートレイルズ流リモートワークのご紹介
 
レッツゴーゆるふわ.Rb
レッツゴーゆるふわ.Rbレッツゴーゆるふわ.Rb
レッツゴーゆるふわ.Rb
 
今すぐAWSが使いたくなる話
今すぐAWSが使いたくなる話今すぐAWSが使いたくなる話
今すぐAWSが使いたくなる話
 
"地方エンジニア" という考え方はすでに終わっている
"地方エンジニア" という考え方はすでに終わっている"地方エンジニア" という考え方はすでに終わっている
"地方エンジニア" という考え方はすでに終わっている
 
信頼される仕事
信頼される仕事信頼される仕事
信頼される仕事
 
ビジネスモデルキャンバス素振り会
ビジネスモデルキャンバス素振り会ビジネスモデルキャンバス素振り会
ビジネスモデルキャンバス素振り会
 
Agile japan 2013 四国サテライト(LT)
Agile japan 2013 四国サテライト(LT)Agile japan 2013 四国サテライト(LT)
Agile japan 2013 四国サテライト(LT)
 
「正しいアジャイル」でなくてもいい
「正しいアジャイル」でなくてもいい「正しいアジャイル」でなくてもいい
「正しいアジャイル」でなくてもいい
 
仲間になろう!~ We are the World ~
仲間になろう!~ We are the World ~仲間になろう!~ We are the World ~
仲間になろう!~ We are the World ~
 
エンジニアがとるべき8つの行動
エンジニアがとるべき8つの行動エンジニアがとるべき8つの行動
エンジニアがとるべき8つの行動
 

Recently uploaded

Alluxio Monthly Webinar | Why a Multi-Cloud Strategy Matters for Your AI Plat...
Alluxio Monthly Webinar | Why a Multi-Cloud Strategy Matters for Your AI Plat...Alluxio Monthly Webinar | Why a Multi-Cloud Strategy Matters for Your AI Plat...
Alluxio Monthly Webinar | Why a Multi-Cloud Strategy Matters for Your AI Plat...Alluxio, Inc.
 
Role of DevOps in SaaS product Development.pdf.pptx
Role of DevOps in SaaS product Development.pdf.pptxRole of DevOps in SaaS product Development.pdf.pptx
Role of DevOps in SaaS product Development.pdf.pptxMindInventory
 
Advanced Globus System Administration Topics
Advanced Globus System Administration TopicsAdvanced Globus System Administration Topics
Advanced Globus System Administration TopicsGlobus
 
Agile & Scrum, Certified Scrum Master! Crash Course
Agile & Scrum,  Certified Scrum Master! Crash CourseAgile & Scrum,  Certified Scrum Master! Crash Course
Agile & Scrum, Certified Scrum Master! Crash CourseRohan Chandane
 
Best Practices for Data Sharing Using Globus
Best Practices for Data Sharing Using GlobusBest Practices for Data Sharing Using Globus
Best Practices for Data Sharing Using GlobusGlobus
 
Workshop híbrido: Stream Processing con Flink
Workshop híbrido: Stream Processing con FlinkWorkshop híbrido: Stream Processing con Flink
Workshop híbrido: Stream Processing con Flinkconfluent
 
Code to Cloud Workshop, Shifting Security to the Left
Code to Cloud Workshop, Shifting Security to the LeftCode to Cloud Workshop, Shifting Security to the Left
Code to Cloud Workshop, Shifting Security to the LeftJamie Coleman
 
Machine Learning Basics for Dummies (no math!)
Machine Learning Basics for Dummies (no math!)Machine Learning Basics for Dummies (no math!)
Machine Learning Basics for Dummies (no math!)Dmitry Zinoviev
 
ey-generative-ai-in-retail-and-commercial-banking (1).pdf
ey-generative-ai-in-retail-and-commercial-banking (1).pdfey-generative-ai-in-retail-and-commercial-banking (1).pdf
ey-generative-ai-in-retail-and-commercial-banking (1).pdfVishveshUpadhyaya
 
Orion Context Broker introduction 20240227
Orion Context Broker introduction 20240227Orion Context Broker introduction 20240227
Orion Context Broker introduction 20240227Fermin Galan
 
Open Source Licence to Kill in Software Development
Open Source Licence to Kill in Software DevelopmentOpen Source Licence to Kill in Software Development
Open Source Licence to Kill in Software DevelopmentJamie Coleman
 
Instrument Data Automation: The Life of a Flow
Instrument Data Automation: The Life of a FlowInstrument Data Automation: The Life of a Flow
Instrument Data Automation: The Life of a FlowGlobus
 
CSS Notes in PDF, Easy to understand. For beginner to advanced. ...
CSS Notes in PDF, Easy to understand. For beginner to advanced.              ...CSS Notes in PDF, Easy to understand. For beginner to advanced.              ...
CSS Notes in PDF, Easy to understand. For beginner to advanced. ...syedfaisal759877
 
Globus for System Administrators
Globus for System AdministratorsGlobus for System Administrators
Globus for System AdministratorsGlobus
 
Building Research Applications with Globus PaaS
Building Research Applications with Globus PaaSBuilding Research Applications with Globus PaaS
Building Research Applications with Globus PaaSGlobus
 
killing camp 주차장 나누기-2 topology sort.pdf
killing camp 주차장 나누기-2 topology sort.pdfkilling camp 주차장 나누기-2 topology sort.pdf
killing camp 주차장 나누기-2 topology sort.pdfssuser82c38d
 
An Introduction to Globus for Researchers
An Introduction to Globus for ResearchersAn Introduction to Globus for Researchers
An Introduction to Globus for ResearchersGlobus
 
Joseph Yoder : Being Agile about Architecture
Joseph Yoder : Being Agile about ArchitectureJoseph Yoder : Being Agile about Architecture
Joseph Yoder : Being Agile about ArchitectureHironori Washizaki
 
How AI is preventing account fraud at web scale
How AI is preventing account fraud at web scaleHow AI is preventing account fraud at web scale
How AI is preventing account fraud at web scaleAmir Moghimi
 
Passbolt Introduction and Usage for secret managment
Passbolt Introduction and Usage for secret managmentPassbolt Introduction and Usage for secret managment
Passbolt Introduction and Usage for secret managmentThierry Gayet
 

Recently uploaded (20)

Alluxio Monthly Webinar | Why a Multi-Cloud Strategy Matters for Your AI Plat...
Alluxio Monthly Webinar | Why a Multi-Cloud Strategy Matters for Your AI Plat...Alluxio Monthly Webinar | Why a Multi-Cloud Strategy Matters for Your AI Plat...
Alluxio Monthly Webinar | Why a Multi-Cloud Strategy Matters for Your AI Plat...
 
Role of DevOps in SaaS product Development.pdf.pptx
Role of DevOps in SaaS product Development.pdf.pptxRole of DevOps in SaaS product Development.pdf.pptx
Role of DevOps in SaaS product Development.pdf.pptx
 
Advanced Globus System Administration Topics
Advanced Globus System Administration TopicsAdvanced Globus System Administration Topics
Advanced Globus System Administration Topics
 
Agile & Scrum, Certified Scrum Master! Crash Course
Agile & Scrum,  Certified Scrum Master! Crash CourseAgile & Scrum,  Certified Scrum Master! Crash Course
Agile & Scrum, Certified Scrum Master! Crash Course
 
Best Practices for Data Sharing Using Globus
Best Practices for Data Sharing Using GlobusBest Practices for Data Sharing Using Globus
Best Practices for Data Sharing Using Globus
 
Workshop híbrido: Stream Processing con Flink
Workshop híbrido: Stream Processing con FlinkWorkshop híbrido: Stream Processing con Flink
Workshop híbrido: Stream Processing con Flink
 
Code to Cloud Workshop, Shifting Security to the Left
Code to Cloud Workshop, Shifting Security to the LeftCode to Cloud Workshop, Shifting Security to the Left
Code to Cloud Workshop, Shifting Security to the Left
 
Machine Learning Basics for Dummies (no math!)
Machine Learning Basics for Dummies (no math!)Machine Learning Basics for Dummies (no math!)
Machine Learning Basics for Dummies (no math!)
 
ey-generative-ai-in-retail-and-commercial-banking (1).pdf
ey-generative-ai-in-retail-and-commercial-banking (1).pdfey-generative-ai-in-retail-and-commercial-banking (1).pdf
ey-generative-ai-in-retail-and-commercial-banking (1).pdf
 
Orion Context Broker introduction 20240227
Orion Context Broker introduction 20240227Orion Context Broker introduction 20240227
Orion Context Broker introduction 20240227
 
Open Source Licence to Kill in Software Development
Open Source Licence to Kill in Software DevelopmentOpen Source Licence to Kill in Software Development
Open Source Licence to Kill in Software Development
 
Instrument Data Automation: The Life of a Flow
Instrument Data Automation: The Life of a FlowInstrument Data Automation: The Life of a Flow
Instrument Data Automation: The Life of a Flow
 
CSS Notes in PDF, Easy to understand. For beginner to advanced. ...
CSS Notes in PDF, Easy to understand. For beginner to advanced.              ...CSS Notes in PDF, Easy to understand. For beginner to advanced.              ...
CSS Notes in PDF, Easy to understand. For beginner to advanced. ...
 
Globus for System Administrators
Globus for System AdministratorsGlobus for System Administrators
Globus for System Administrators
 
Building Research Applications with Globus PaaS
Building Research Applications with Globus PaaSBuilding Research Applications with Globus PaaS
Building Research Applications with Globus PaaS
 
killing camp 주차장 나누기-2 topology sort.pdf
killing camp 주차장 나누기-2 topology sort.pdfkilling camp 주차장 나누기-2 topology sort.pdf
killing camp 주차장 나누기-2 topology sort.pdf
 
An Introduction to Globus for Researchers
An Introduction to Globus for ResearchersAn Introduction to Globus for Researchers
An Introduction to Globus for Researchers
 
Joseph Yoder : Being Agile about Architecture
Joseph Yoder : Being Agile about ArchitectureJoseph Yoder : Being Agile about Architecture
Joseph Yoder : Being Agile about Architecture
 
How AI is preventing account fraud at web scale
How AI is preventing account fraud at web scaleHow AI is preventing account fraud at web scale
How AI is preventing account fraud at web scale
 
Passbolt Introduction and Usage for secret managment
Passbolt Introduction and Usage for secret managmentPassbolt Introduction and Usage for secret managment
Passbolt Introduction and Usage for secret managment
 

Designing Practical RESTful APIs

  • 2. Who am I? • Hiroshi Ogino • web developer • home-based worker • founder of @yurufuwarb
  • 3. Agenda • What is REST? • How should we design practical APIs? • Conclusion
  • 4. Agenda • What is REST? • How should we design practical APIs? • Conclusion
  • 5. REST • REpresentational State Transfer • Architecture style, where data and functionality are accessed as URIs • Simple, Lightweight, and Fast
  • 7. REST • Resource-Oriented • Uniform Interface • Stateless
  • 8. Resource-Oriented • Addressable, Indexable • Resources are identified as Uniform Resource Identifiers (URIs) • Connectedness • Resources should link together in their representation
  • 10. The world is filled with a lot of resources
  • 12. REST • Resource-Oriented • Uniform Interface • Stateless
  • 13. HTTP METHODS Uniform Resource Locator (URL) GET PUT PATCH POST DELETE Collection https://api.xxx/items List details of the collection Replace the entire collection with another one Not generally used Create a new entry in the collection Delete a entire collection Element https://api.xxx/items/12 Retrieve a representation of the member of the collection Replace the member of the collection, or Create it if it does not exist Update the member of the collection Not generally used Delete the member of the collection
  • 14. REST • Resource-Oriented • Uniform Interface • Stateless
  • 16. Hi, for here or to go? For here. STATEFUL
  • 17. What can I get you? Can I have two cheeseburgers and one order of fries? STATEFUL
  • 18. What size fries would you like? Small. STATEFUL
  • 19. Would you like anything to drink? I’ll have coke. STATEFUL
  • 20. Would you like anything else? No, I’m good. STATEFUL
  • 21. STATEFUL • Cashier remembers your past orders • You only have to put your latest order
  • 22. Hi, for here or to go? For here. STATELESS
  • 23. What can I get you? For here. Can I have two cheeseburgers and one order of fries? STATELESS
  • 24. What size fries would you like? For here. Can I have two cheeseburgers and one order of fries? Small. STATELESS
  • 25. Would you like anything to drink? For here. Can I have two cheeseburgers and one order of fries? Small. I’ll have coke. STATELESS
  • 26. STATELESS • Cashier DOES NOT remember your past orders • You have to put orders including past orders
  • 27. STATELESS • Cashier DOES NOT remember your past orders • You have to put orders including past orders What good will come of it? 🤔
  • 28. STATELESS • It was said that the main advantage of STATELESS was SCALABILITY in the past • It was believed that STATEFUL COULD NOT scale out
  • 29. STATELESS • It was said that the main advantage of STATELESS was SCALABILITY in the past • It was believed that STATEFUL COULD NOT scale out • Nowadays … • LB can dispatch the same server which is scaled out • scaled out servers can share the same session store (RDS, Redis, …) It’s no longer a big deal!
  • 30. Agenda • What is REST? • How should we design practical APIs? • Conclusion
  • 32. Practical • Dictionary says • involving activity rather than study or theory • likely to be successful or useful
  • 33. Practical SHU-HA-RI is a Japanese martial art concept, and describes the stage of learning to mastery
  • 34. Practical Repeat the forms and discipline ourselves to absorb the forms and to find the values lurking behind them SHU → obey, protect
  • 35. Practical Based on the fundamentals learned with break the forms and make innovation HA → detach ,
  • 36. Practical Completely depart from the forms, act in accordance with what we want RI → leave
  • 37. Practical Find the key to PRACTICAL hiding around here
  • 38. Practical • Dictionary says • involving activity rather than study or theory • likely to be successful or useful • MAY NOT OBEY all constraints of the REST architecture style • BREAK theory now and then for a specific purpose • FOCUS ON successful / useful
  • 40. Q.1 How should we design the ENDPOINT to get our own information?
  • 41. GET /customers/:id From GET method, easy to expect retrieving the customer information from customers table while requesting Anyone CAN GUESS other’s endpoints
  • 42. GET /me or /mypage From GET method, easy to expect retrieving my information from customers table while requesting Anyone CAN NOT GUESS other’s endpoints
  • 43. However, we need to store customer_id in a session to identify the customer and it makes this endpoint STATEFUL … is it okay? 🤔 GET /me or /mypage
  • 44. STATELESS • It was said that the main advantage of STATELESS was SCALABILITY in the past • It was believed that STATEFUL COULD NOT scale out • Nowadays … • LB can dispatch the same server which is scaled out • scaled out servers can share the same session store (RDS, Redis, …) It’s no longer a big deal!
  • 45. REMAINS scalable even if we store customer_id in a session Caution: we should not manage long-life objects in a session because it may deprive the independency of each request GET /me or /mypage
  • 46. Learned from Q.1 • SHOULD NOT allow anyone to guess the other’s endpoints if the resources of the endpoint are serious information • CAN use a session for a specific purpose
  • 47. Q.2 How should we design the RESOURCE and the ENDPOINT that allow customers to agree with the Terms of Service?
  • 48. Q.2 How should we design the RESOURCE and the ENDPOINT that allow customers to agree with the Terms of Service?
  • 49. This resource CAN NOT represent updating Terms of Service This resource CAN NOT manage enforced datetime id int nickname string : agreement booleancustomers ADD agreement column to customers table
  • 50. This resource CAN represent updating Terms of Service This resource CAN manage enforced datetime ● enforced date is managed by version column ● enforced datetime is managed by start_at column CREATE terms / terms_agreement tables customers term_agreements terms id int version string start_at datetime : id int customer_id int term_id int :
  • 51. Q.2 How should we design the RESOURCE and the ENDPOINT that allow customers to agree with the Terms of Service?
  • 52. :version is enforced date (ex. /terms/20180515/agreements) clear to agree with which version of terms From POST method, easy to expect inserting a new term agreement record while requesting POST /terms/:version/agreements
  • 53. Learned from Q.2 • SHOULD maximize representation of a resource • SHOULD make an Endpoint semantic
  • 54. Q.3 How should we design the SEQUENCE in which customers buy something in an application?
  • 55. Back-end ServerCustomer https://api.example.com/items Network (1) SEARCH Back-end ServerCustomer Network (2) CONFIRM Back-end ServerCustomer Network (3) PURCHASE https://api.example.com/items/order? confirm=true https://api.example.com/items/order
  • 56. Customer STORE purchase data CONFIRM Network Back-end Server Session Store COMPLETE confirmation PURCHASE VALIDATE purchase data DELETE purchase data PROCESS purchase COMPLETE purchase - (2) CONFIRM - (3) PURCHASE
  • 57. Customer STORE purchase data CONFIRM Network Back-end Server Session Store PURCHASE VALIDATE purchase data DELETE purchase data PROCESS purchase - PREVENT duplicated requests COMPLETE confirmation COMPLETE purchase
  • 58. Learned from Q.3 • SHOULD establish a confirmation phase to operate significant action, such as a purchase • MUST use a session intentionally to prevent duplicated requests
  • 59. Agenda • What is REST? • How should we design practical APIs? • Conclusion
  • 60. Learned from Q.1 • SHOULD NOT allow anyone to guess the other’s endpoints if the resources of the endpoint are serious information • CAN use a session for a specific purpose
  • 61. Learned from Q.2 • SHOULD maximize representation of a resource • SHOULD make an Endpoint semantic
  • 62. Learned from Q.3 • SHOULD establish a confirmation phase to operate significant action, such as a purchase • MUST use a session intentionally to prevent duplicated requests