SlideShare a Scribd company logo
RESTFUL API CONCEPTS
AND BEST PRACTICES
Yazan Qutieshat
Tambi Jalouqa
Senior Software Engineer at Souq.com a subsidiary of amazon
Head of Products at Propeller inc.
Working on a social media aggregator opened my eyes to
many restful APIs such as (Facebook, Twitter, Instagram…)
How i used to create API’s
`GET /getComments/` [Get Comments]
`POST /addComment/` [Add a Comment]
`POST /deleteComment/` [Delete a Comment]
MY STORY
How Facebook API's work
`GET /posts/{post_id}/comments` [Get Comments]
`POST /posts/{post_id}/comments` [Add a Comment]

`DELETE /comments/{comment_id}` [Delete a Comment]
RESTFUL ARCHITECTURE
WHAT MAKES AN API
RESTFUL
Representational state transfer (REST) or RESTful web
services is a way of providing interoperability between
computer systems on the Internet. REST-compliant Web
services allow requesting systems to access and manipulate
textual representations of Web resources using a uniform
and predefined set of stateless operations.
RESTFUL ARCHITECTURE
WHAT MAKES AN API
RESTFUL
REST is the underlying architectural principle of the web. The
amazing thing about the web is the fact that clients and
servers can interact in complex ways without the client
knowing anything beforehand about the server and the
resources it hosts.
ARCHITECTURAL STYLE
THE SIMPLE VERSION
A set of guidelines (attributes and characteristic) that aims to
design a single interface that reflect your business to all
your consumers while being stateless and readable.
WHAT MAKES AN API
RESTFUL
The main ingredients of a Restful Api
• Resources
• Protocol (Http)
• Headers
• Methods
• Status Codes
The Guidelines
WHAT MAKES AN API
RESTFUL
Resources :
Any abstraction of information that has a meaning in your
domain (business)
The Guidelines
• Virtual object.
• Singleton or a Collection
• List of available options.
• Result of a mathematical operation.
WHAT MAKES AN API
RESTFUL
Protocol (HTTP) :
Methods :
Use Methods to Retrieve and Manipulate (Creation, Mutation) resources.
The Guidelines
• GET [Retrieve] : Safe, Idempotent , Cacheable
• PUT [update] : Idempotent
• DELETE [delete]: Idempotent
• PATCH [Partial update] : Idempotent
• POST [Create]
WHAT MAKES AN API
RESTFUL
Protocol (HTTP) :
Status Codes :
Use Status Codes to inform how client how he should proceed.
The Guidelines
• Successful 2xx (200 Successful, 201 Created, 204 No Content)
• Multiple choices 3xx (301 Moved, 302 Found, 304 Not Modified)
• User Errors 4xx (401 Unauthorized, 403 Forbidden, 404 Not
Found, 422 Unprocessable Entity )
• Server Errors 5xx
THE ALTERNATIVES
SOAP
RPC
GRAPH
THE ALTERNATIVES
RPC
Remote Procedure Call (RPC) is a protocol that one program
can use to request a service from a program located in another
computer on a network without having to understand the
network's details. A procedure call is also sometimes known as
a function call or a subroutine call
• Complicated
• Lacks consistency
• Oriented around procedures
THE ALTERNATIVES
SOAP
It is method for exchanging XML based message over the
Internet for providing and consuming web services. SOAP
message are transferred forming the SOAP-Envelope.
• Rigid
• Requires Development
• Requires Knowledge
THE ALTERNATIVES
GRAPH QL
Instead of working with rigid server-defined endpoints, you can
send queries to get exactly the data you’re looking for in one
request
• Still Young
• Requires domain knowledge
• Coupled with the backend
BENEFITS
• Simple
• Scalable
• Cacheable
• Testable
REINVENTING THE
WHEEL
Authentication (Basic, OAuth, JWT)
Security (ACL, CORS)
Traffic control (Rate Limiting, Termination)
Logging
TOOLS
TOOLS
Word Documents
DOCUMENTATION
TOOLS
Apiary (Blueprint)
DOCUMENTATION
TOOLS
Swagger
DOCUMENTATION
TOOLS
API Gateway AWS
Apigee
Kong
MANAGEMENT
TOOLS
Acceptance Testing
Continuous Integration
TESTING
THANK YOU
END OF PART ONE
BEST PRACTICES FOR
CREATING A RESTFUL
API
API FIRST DEVELOPMENT
Lets start with a story about a mountain bike trail
I LOVE MOUNTAIN BIKING
AND THATS WHY I BUILD
TRAILS
BUT BUILDING TRAILS IS
HARD AND REQUIRES
TRAIL DESIGN
HEAVY MACHINERY COMES
LAST. MARKING WITH STICK
AND STONE IS FIRST
SKETCHING VS PIXEL
PERFECT DESIGN
• Include the team
• Allow change to happen
• Faster feedback loop
TREAT YOUR API LIKE A
CONSUMER PRODUCT
Consumers of your API should be treated as if they are going
to pay for it.
Do not take them for granted.
They will either move on or have a bad experience.
USER EXPERIENCE
USER EXPERIENCE
Using the proper language while naming your endpoints and
resources will help users understand how to use your API.
Using nouns vs verbs helps set the mental model for using
the API.
COMMUNICATE PROPERLY
Use

POST /people
Instead of 

POST /addPerson
Be consistent in your return status codes. Try to use a few
but well understood status codes such as 200, 201, 403
Do not re-define status codes in a way that will confuse
users. Returning a 201 when a resource is edited will
confuse the user and increase cognitive load.
BE FAMILIAR
USER EXPERIENCE
Be clear about the wrong ways of using your API. If you require
a certain schema return an error that is descriptive of what is
the issue. Invalid keys, invalid datatypes, required fields that
are empty.
You will make solving issues while using the API much faster if
you are clear and helpful.
ALWAYS GIVE USEFUL FEEDBACK
USER EXPERIENCE
Always return the same schema or status code for the same
operations if possible
This will help users re-use their learned behavior
For example they can create an abstraction around using your
API
BE CONSISTENT
USER EXPERIENCE
Implement a consistent pagination, filtering or relations in
your API
Different users will have different needs. One user might
want the whole collection while another will only need a few
pages. Mobile clients would try to be bandwidth conservative
and only ask for what they need.
DESIGN FOR DIFFERENT USE


GET /people?fields=firstname,lastname&limit=10&skip=3
USER EXPERIENCE
HELP USERS BE SMARTER
USER EXPERIENCE
HELP USERS BE SMARTER
Specify the life of your returned results. Add meta data to
allow smart users to cache your data to reduce chatter and
allow for offline experiences.
Use ETag or Last-Modified to allow users to know if a
resource has been updated and they will receive fresh data
from your API
USER EXPERIENCE
USER EXPERIENCE
BE BACKWARDS COMPATIBLE
Versioning your api will allow for users that have not updated
their code to continue interacting with your API
This allows for an incremental move to a newer version on
their own paces. But always give them a push toward newer
better versions.
Available options are URI based versioning or the Accept
header or custom request headers.
COMMON PITFALLS
Many times API designers tend to crudify their APIs
Always think about each resource and how it fits your
domain. Sometimes a resource will only allow for creating a
new resource and not editing it.
ALWAYS USING CRUD
COMMON PITFALLS
e.g. financial transactions

POST /transactions
Transactions will not accept PUT, PATCH, DELETE
Changes to an API that will break existing clients need to be
clear. If the interface changes underneath without them
knowing it systems will break.
As discussed before always increment the available version
and help onboard users to the newer API
Always communicate upcoming changes and create the
proper channels to facilitate that
NOT USING VERSIONING
COMMON PITFALLS
COMMON PITFALLS
Designing an API without the proper feedback loop will
guarantee that your API is not usable.
Not taking the users into consideration will create an API that
is not user-centered and will require a re-design for new use
cases.
NOT INCLUDING YOUR
STAKEHOLDERS
COMMON PITFALLS
Use industry standards to document your API, Swagger,
Blueprint, RAML, etc.
Having the users to either ask for the schema or read
through your code to understand usage of your API is a
recipe for disaster.
NOT DOCUMENTING
ALWAYS BE DESIGNING
THE API IS A CONSUMER FACING
PRODUCT, TREAT THEM THAT WAY.
THANK YOU
END OF PART TWO
Q&A
Yazan Qutieshat
Tambi Jalouqa
Senior Software Engineer at Souq.com a subsidiary of amazon

yazan.qutieshat@gmail.com
Head of Products at Propeller inc. 

tambi@propellerinc.me

More Related Content

What's hot

React js
React jsReact js
React js
Alireza Akbari
 
Getting Started with React-Nathan Smith
Getting Started with React-Nathan SmithGetting Started with React-Nathan Smith
Getting Started with React-Nathan Smith
TandemSeven
 
React-js
React-jsReact-js
React-js
Avi Kedar
 
Internal workshop react-js-mruiz
Internal workshop react-js-mruizInternal workshop react-js-mruiz
Internal workshop react-js-mruiz
Miguel Ruiz Rodriguez
 
React js basics
React js basicsReact js basics
React js basics
Maulik Shah
 
Tech Talk on ReactJS
Tech Talk on ReactJSTech Talk on ReactJS
Tech Talk on ReactJS
Atlogys Technical Consulting
 
React js programming concept
React js programming conceptReact js programming concept
React js programming concept
Tariqul islam
 
Fundamental concepts of react js
Fundamental concepts of react jsFundamental concepts of react js
Fundamental concepts of react js
StephieJohn
 
React js Rahil Memon
React js Rahil MemonReact js Rahil Memon
React js Rahil Memon
RahilMemon5
 
[React Native Tutorial] Lecture 6: Component, Props, and Network
[React Native Tutorial] Lecture 6: Component, Props, and Network[React Native Tutorial] Lecture 6: Component, Props, and Network
[React Native Tutorial] Lecture 6: Component, Props, and Network
Kobkrit Viriyayudhakorn
 
React introduction
React introductionReact introduction
React introduction
Kashyap Parmar
 
Ryan Christiani I Heard React Was Good
Ryan Christiani I Heard React Was GoodRyan Christiani I Heard React Was Good
Ryan Christiani I Heard React Was Good
FITC
 
React JS
React JSReact JS
learning react
learning reactlearning react
learning react
Eueung Mulyana
 
An Overview of the React Ecosystem
An Overview of the React EcosystemAn Overview of the React Ecosystem
An Overview of the React Ecosystem
FITC
 
How native is React Native? | React Native vs Native App Development
How native is React Native? | React Native vs Native App DevelopmentHow native is React Native? | React Native vs Native App Development
How native is React Native? | React Native vs Native App Development
Devathon
 
Intro to React
Intro to ReactIntro to React
Intro to React
Justin Reock
 
Top 8 benefits of react js
Top 8 benefits of react jsTop 8 benefits of react js
Top 8 benefits of react js
Rani Sinha
 
React workshop
React workshopReact workshop
React workshop
Imran Sayed
 
Introduction to react
Introduction to reactIntroduction to react
Introduction to react
kiranabburi
 

What's hot (20)

React js
React jsReact js
React js
 
Getting Started with React-Nathan Smith
Getting Started with React-Nathan SmithGetting Started with React-Nathan Smith
Getting Started with React-Nathan Smith
 
React-js
React-jsReact-js
React-js
 
Internal workshop react-js-mruiz
Internal workshop react-js-mruizInternal workshop react-js-mruiz
Internal workshop react-js-mruiz
 
React js basics
React js basicsReact js basics
React js basics
 
Tech Talk on ReactJS
Tech Talk on ReactJSTech Talk on ReactJS
Tech Talk on ReactJS
 
React js programming concept
React js programming conceptReact js programming concept
React js programming concept
 
Fundamental concepts of react js
Fundamental concepts of react jsFundamental concepts of react js
Fundamental concepts of react js
 
React js Rahil Memon
React js Rahil MemonReact js Rahil Memon
React js Rahil Memon
 
[React Native Tutorial] Lecture 6: Component, Props, and Network
[React Native Tutorial] Lecture 6: Component, Props, and Network[React Native Tutorial] Lecture 6: Component, Props, and Network
[React Native Tutorial] Lecture 6: Component, Props, and Network
 
React introduction
React introductionReact introduction
React introduction
 
Ryan Christiani I Heard React Was Good
Ryan Christiani I Heard React Was GoodRyan Christiani I Heard React Was Good
Ryan Christiani I Heard React Was Good
 
React JS
React JSReact JS
React JS
 
learning react
learning reactlearning react
learning react
 
An Overview of the React Ecosystem
An Overview of the React EcosystemAn Overview of the React Ecosystem
An Overview of the React Ecosystem
 
How native is React Native? | React Native vs Native App Development
How native is React Native? | React Native vs Native App DevelopmentHow native is React Native? | React Native vs Native App Development
How native is React Native? | React Native vs Native App Development
 
Intro to React
Intro to ReactIntro to React
Intro to React
 
Top 8 benefits of react js
Top 8 benefits of react jsTop 8 benefits of react js
Top 8 benefits of react js
 
React workshop
React workshopReact workshop
React workshop
 
Introduction to react
Introduction to reactIntroduction to react
Introduction to react
 

Similar to JOSA TechTalks - RESTful API Concepts and Best Practices

Business Applications Integration In The Cloud
Business Applications Integration In The CloudBusiness Applications Integration In The Cloud
Business Applications Integration In The Cloud
Anna Brzezińska
 
Building the Eventbrite API Ecosystem
Building the Eventbrite API EcosystemBuilding the Eventbrite API Ecosystem
Building the Eventbrite API Ecosystem
Mitch Colleran
 
Best practices and advantages of REST APIs
Best practices and advantages of REST APIsBest practices and advantages of REST APIs
Best practices and advantages of REST APIs
Aparna Sharma
 
apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...
apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...
apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...
apidays
 
The ultimate api checklist by Blendr.io
The ultimate api checklist by Blendr.ioThe ultimate api checklist by Blendr.io
The ultimate api checklist by Blendr.io
Blendr.io
 
Open Banking & Open Insurance
Open Banking & Open InsuranceOpen Banking & Open Insurance
Open Banking & Open Insurance
Amazon Web Services
 
MuleSoft Surat Virtual Meetup#21 - MuleSoft API and RAML Design Best Practice...
MuleSoft Surat Virtual Meetup#21 - MuleSoft API and RAML Design Best Practice...MuleSoft Surat Virtual Meetup#21 - MuleSoft API and RAML Design Best Practice...
MuleSoft Surat Virtual Meetup#21 - MuleSoft API and RAML Design Best Practice...
Jitendra Bafna
 
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.pptx
apidays
 
DataHero / Eventbrite - API Best Practices
DataHero / Eventbrite - API Best PracticesDataHero / Eventbrite - API Best Practices
DataHero / Eventbrite - API Best Practices
Jeff Zabel
 
RefCard API Architecture Strategy
RefCard API Architecture StrategyRefCard API Architecture Strategy
RefCard API Architecture Strategy
OCTO Technology
 
Api design part 1
Api design part 1Api design part 1
Api design part 1
Ibrahim Elsawaf
 
Asynchronous API Testing: Trends, Tools & More | Calidad Infotech
Asynchronous API Testing: Trends, Tools & More | Calidad Infotech Asynchronous API Testing: Trends, Tools & More | Calidad Infotech
Asynchronous API Testing: Trends, Tools & More | Calidad Infotech
Calidad Infotech
 
Do not automate GUI testing
Do not automate GUI testingDo not automate GUI testing
Do not automate GUI testing
Atila Inovecký
 
Java Test Automation for REST, Web and Mobile
Java Test Automation for REST, Web and MobileJava Test Automation for REST, Web and Mobile
Java Test Automation for REST, Web and Mobile
Elias Nogueira
 
M meijer api management - tech-days 2015
M meijer   api management - tech-days 2015M meijer   api management - tech-days 2015
M meijer api management - tech-days 2015
Freelance Consultant / Manager / co-CTO
 
Oracle API Platform Cloud Service Best Practices & Lessons Learnt
Oracle API Platform Cloud Service Best Practices & Lessons LearntOracle API Platform Cloud Service Best Practices & Lessons Learnt
Oracle API Platform Cloud Service Best Practices & Lessons Learnt
luisw19
 
Crafting APIs
Crafting APIsCrafting APIs
Crafting APIs
Tatiana Al-Chueyr
 
Azure API Management - why should I care?
Azure API Management - why should I care?Azure API Management - why should I care?
Azure API Management - why should I care?
Jouni Heikniemi
 

Similar to JOSA TechTalks - RESTful API Concepts and Best Practices (20)

Business Applications Integration In The Cloud
Business Applications Integration In The CloudBusiness Applications Integration In The Cloud
Business Applications Integration In The Cloud
 
Building the Eventbrite API Ecosystem
Building the Eventbrite API EcosystemBuilding the Eventbrite API Ecosystem
Building the Eventbrite API Ecosystem
 
Best practices and advantages of REST APIs
Best practices and advantages of REST APIsBest practices and advantages of REST APIs
Best practices and advantages of REST APIs
 
apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...
apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...
apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...
 
The ultimate api checklist by Blendr.io
The ultimate api checklist by Blendr.ioThe ultimate api checklist by Blendr.io
The ultimate api checklist by Blendr.io
 
Open Banking & Open Insurance
Open Banking & Open InsuranceOpen Banking & Open Insurance
Open Banking & Open Insurance
 
MuleSoft Surat Virtual Meetup#21 - MuleSoft API and RAML Design Best Practice...
MuleSoft Surat Virtual Meetup#21 - MuleSoft API and RAML Design Best Practice...MuleSoft Surat Virtual Meetup#21 - MuleSoft API and RAML Design Best Practice...
MuleSoft Surat Virtual Meetup#21 - MuleSoft API and RAML Design Best Practice...
 
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.pptx
 
DataHero / Eventbrite - API Best Practices
DataHero / Eventbrite - API Best PracticesDataHero / Eventbrite - API Best Practices
DataHero / Eventbrite - API Best Practices
 
RefCard API Architecture Strategy
RefCard API Architecture StrategyRefCard API Architecture Strategy
RefCard API Architecture Strategy
 
Api design part 1
Api design part 1Api design part 1
Api design part 1
 
APITalkMeetupSharable
APITalkMeetupSharableAPITalkMeetupSharable
APITalkMeetupSharable
 
Asynchronous API Testing: Trends, Tools & More | Calidad Infotech
Asynchronous API Testing: Trends, Tools & More | Calidad Infotech Asynchronous API Testing: Trends, Tools & More | Calidad Infotech
Asynchronous API Testing: Trends, Tools & More | Calidad Infotech
 
Do not automate GUI testing
Do not automate GUI testingDo not automate GUI testing
Do not automate GUI testing
 
Java Test Automation for REST, Web and Mobile
Java Test Automation for REST, Web and MobileJava Test Automation for REST, Web and Mobile
Java Test Automation for REST, Web and Mobile
 
M meijer api management - tech-days 2015
M meijer   api management - tech-days 2015M meijer   api management - tech-days 2015
M meijer api management - tech-days 2015
 
Oracle API Platform Cloud Service Best Practices & Lessons Learnt
Oracle API Platform Cloud Service Best Practices & Lessons LearntOracle API Platform Cloud Service Best Practices & Lessons Learnt
Oracle API Platform Cloud Service Best Practices & Lessons Learnt
 
Crafting APIs
Crafting APIsCrafting APIs
Crafting APIs
 
Api Testing.pdf
Api Testing.pdfApi Testing.pdf
Api Testing.pdf
 
Azure API Management - why should I care?
Azure API Management - why should I care?Azure API Management - why should I care?
Azure API Management - why should I care?
 

More from Jordan Open Source Association

JOSA TechTalks - Data Oriented Architecture
JOSA TechTalks - Data Oriented ArchitectureJOSA TechTalks - Data Oriented Architecture
JOSA TechTalks - Data Oriented Architecture
Jordan Open Source Association
 
JOSA TechTalks - Machine Learning on Graph-Structured Data
JOSA TechTalks - Machine Learning on Graph-Structured DataJOSA TechTalks - Machine Learning on Graph-Structured Data
JOSA TechTalks - Machine Learning on Graph-Structured Data
Jordan Open Source Association
 
OpenSooq Mobile Infrastructure @ Scale
OpenSooq Mobile Infrastructure @ ScaleOpenSooq Mobile Infrastructure @ Scale
OpenSooq Mobile Infrastructure @ Scale
Jordan Open Source Association
 
Data-Driven Digital Transformation
Data-Driven Digital TransformationData-Driven Digital Transformation
Data-Driven Digital Transformation
Jordan Open Source Association
 
Data Science in Action
Data Science in ActionData Science in Action
Data Science in Action
Jordan Open Source Association
 
Processing Arabic Text
Processing Arabic TextProcessing Arabic Text
Processing Arabic Text
Jordan Open Source Association
 
JOSA TechTalks - Downgrade your Costs
JOSA TechTalks - Downgrade your CostsJOSA TechTalks - Downgrade your Costs
JOSA TechTalks - Downgrade your Costs
Jordan Open Source Association
 
JOSA TechTalks - Docker in Production
JOSA TechTalks - Docker in ProductionJOSA TechTalks - Docker in Production
JOSA TechTalks - Docker in Production
Jordan Open Source Association
 
JOSA TechTalks - Word Embedding and Word2Vec Explained
JOSA TechTalks - Word Embedding and Word2Vec ExplainedJOSA TechTalks - Word Embedding and Word2Vec Explained
JOSA TechTalks - Word Embedding and Word2Vec Explained
Jordan Open Source Association
 
Web app architecture
Web app architectureWeb app architecture
Web app architecture
Jordan Open Source Association
 
Intro to the Principles of Graphic Design
Intro to the Principles of Graphic DesignIntro to the Principles of Graphic Design
Intro to the Principles of Graphic Design
Jordan Open Source Association
 
Intro to Graphic Design Elements
Intro to Graphic Design ElementsIntro to Graphic Design Elements
Intro to Graphic Design Elements
Jordan Open Source Association
 
JOSA TechTalk: Realtime monitoring and alerts
JOSA TechTalk: Realtime monitoring and alerts JOSA TechTalk: Realtime monitoring and alerts
JOSA TechTalk: Realtime monitoring and alerts
Jordan Open Source Association
 
JOSA TechTalk: Metadata Management
in Big Data
JOSA TechTalk: Metadata Management
in Big DataJOSA TechTalk: Metadata Management
in Big Data
JOSA TechTalk: Metadata Management
in Big Data
Jordan Open Source Association
 
JOSA TechTalk: Introduction to Supervised Learning
JOSA TechTalk: Introduction to Supervised LearningJOSA TechTalk: Introduction to Supervised Learning
JOSA TechTalk: Introduction to Supervised Learning
Jordan Open Source Association
 
JOSA TechTalk: Taking Docker to Production
JOSA TechTalk: Taking Docker to ProductionJOSA TechTalk: Taking Docker to Production
JOSA TechTalk: Taking Docker to Production
Jordan Open Source Association
 
JOSA TechTalk: Introduction to docker
JOSA TechTalk: Introduction to dockerJOSA TechTalk: Introduction to docker
JOSA TechTalk: Introduction to docker
Jordan Open Source Association
 
D programming language
D programming languageD programming language
D programming language
Jordan Open Source Association
 
A taste of Functional Programming
A taste of Functional ProgrammingA taste of Functional Programming
A taste of Functional Programming
Jordan Open Source Association
 
JOSA TechTalks - Machine Learning in Practice
JOSA TechTalks - Machine Learning in PracticeJOSA TechTalks - Machine Learning in Practice
JOSA TechTalks - Machine Learning in Practice
Jordan Open Source Association
 

More from Jordan Open Source Association (20)

JOSA TechTalks - Data Oriented Architecture
JOSA TechTalks - Data Oriented ArchitectureJOSA TechTalks - Data Oriented Architecture
JOSA TechTalks - Data Oriented Architecture
 
JOSA TechTalks - Machine Learning on Graph-Structured Data
JOSA TechTalks - Machine Learning on Graph-Structured DataJOSA TechTalks - Machine Learning on Graph-Structured Data
JOSA TechTalks - Machine Learning on Graph-Structured Data
 
OpenSooq Mobile Infrastructure @ Scale
OpenSooq Mobile Infrastructure @ ScaleOpenSooq Mobile Infrastructure @ Scale
OpenSooq Mobile Infrastructure @ Scale
 
Data-Driven Digital Transformation
Data-Driven Digital TransformationData-Driven Digital Transformation
Data-Driven Digital Transformation
 
Data Science in Action
Data Science in ActionData Science in Action
Data Science in Action
 
Processing Arabic Text
Processing Arabic TextProcessing Arabic Text
Processing Arabic Text
 
JOSA TechTalks - Downgrade your Costs
JOSA TechTalks - Downgrade your CostsJOSA TechTalks - Downgrade your Costs
JOSA TechTalks - Downgrade your Costs
 
JOSA TechTalks - Docker in Production
JOSA TechTalks - Docker in ProductionJOSA TechTalks - Docker in Production
JOSA TechTalks - Docker in Production
 
JOSA TechTalks - Word Embedding and Word2Vec Explained
JOSA TechTalks - Word Embedding and Word2Vec ExplainedJOSA TechTalks - Word Embedding and Word2Vec Explained
JOSA TechTalks - Word Embedding and Word2Vec Explained
 
Web app architecture
Web app architectureWeb app architecture
Web app architecture
 
Intro to the Principles of Graphic Design
Intro to the Principles of Graphic DesignIntro to the Principles of Graphic Design
Intro to the Principles of Graphic Design
 
Intro to Graphic Design Elements
Intro to Graphic Design ElementsIntro to Graphic Design Elements
Intro to Graphic Design Elements
 
JOSA TechTalk: Realtime monitoring and alerts
JOSA TechTalk: Realtime monitoring and alerts JOSA TechTalk: Realtime monitoring and alerts
JOSA TechTalk: Realtime monitoring and alerts
 
JOSA TechTalk: Metadata Management
in Big Data
JOSA TechTalk: Metadata Management
in Big DataJOSA TechTalk: Metadata Management
in Big Data
JOSA TechTalk: Metadata Management
in Big Data
 
JOSA TechTalk: Introduction to Supervised Learning
JOSA TechTalk: Introduction to Supervised LearningJOSA TechTalk: Introduction to Supervised Learning
JOSA TechTalk: Introduction to Supervised Learning
 
JOSA TechTalk: Taking Docker to Production
JOSA TechTalk: Taking Docker to ProductionJOSA TechTalk: Taking Docker to Production
JOSA TechTalk: Taking Docker to Production
 
JOSA TechTalk: Introduction to docker
JOSA TechTalk: Introduction to dockerJOSA TechTalk: Introduction to docker
JOSA TechTalk: Introduction to docker
 
D programming language
D programming languageD programming language
D programming language
 
A taste of Functional Programming
A taste of Functional ProgrammingA taste of Functional Programming
A taste of Functional Programming
 
JOSA TechTalks - Machine Learning in Practice
JOSA TechTalks - Machine Learning in PracticeJOSA TechTalks - Machine Learning in Practice
JOSA TechTalks - Machine Learning in Practice
 

Recently uploaded

Understanding Globus Data Transfers with NetSage
Understanding Globus Data Transfers with NetSageUnderstanding Globus Data Transfers with NetSage
Understanding Globus Data Transfers with NetSage
Globus
 
BoxLang: Review our Visionary Licenses of 2024
BoxLang: Review our Visionary Licenses of 2024BoxLang: Review our Visionary Licenses of 2024
BoxLang: Review our Visionary Licenses of 2024
Ortus Solutions, Corp
 
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Hivelance Technology
 
Prosigns: Transforming Business with Tailored Technology Solutions
Prosigns: Transforming Business with Tailored Technology SolutionsProsigns: Transforming Business with Tailored Technology Solutions
Prosigns: Transforming Business with Tailored Technology Solutions
Prosigns
 
GlobusWorld 2024 Opening Keynote session
GlobusWorld 2024 Opening Keynote sessionGlobusWorld 2024 Opening Keynote session
GlobusWorld 2024 Opening Keynote session
Globus
 
Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus Compute wth IRI Workflows - GlobusWorld 2024Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus
 
Globus Connect Server Deep Dive - GlobusWorld 2024
Globus Connect Server Deep Dive - GlobusWorld 2024Globus Connect Server Deep Dive - GlobusWorld 2024
Globus Connect Server Deep Dive - GlobusWorld 2024
Globus
 
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Globus
 
Lecture 1 Introduction to games development
Lecture 1 Introduction to games developmentLecture 1 Introduction to games development
Lecture 1 Introduction to games development
abdulrafaychaudhry
 
Strategies for Successful Data Migration Tools.pptx
Strategies for Successful Data Migration Tools.pptxStrategies for Successful Data Migration Tools.pptx
Strategies for Successful Data Migration Tools.pptx
varshanayak241
 
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
XfilesPro
 
First Steps with Globus Compute Multi-User Endpoints
First Steps with Globus Compute Multi-User EndpointsFirst Steps with Globus Compute Multi-User Endpoints
First Steps with Globus Compute Multi-User Endpoints
Globus
 
De mooiste recreatieve routes ontdekken met RouteYou en FME
De mooiste recreatieve routes ontdekken met RouteYou en FMEDe mooiste recreatieve routes ontdekken met RouteYou en FME
De mooiste recreatieve routes ontdekken met RouteYou en FME
Jelle | Nordend
 
OpenFOAM solver for Helmholtz equation, helmholtzFoam / helmholtzBubbleFoam
OpenFOAM solver for Helmholtz equation, helmholtzFoam / helmholtzBubbleFoamOpenFOAM solver for Helmholtz equation, helmholtzFoam / helmholtzBubbleFoam
OpenFOAM solver for Helmholtz equation, helmholtzFoam / helmholtzBubbleFoam
takuyayamamoto1800
 
Providing Globus Services to Users of JASMIN for Environmental Data Analysis
Providing Globus Services to Users of JASMIN for Environmental Data AnalysisProviding Globus Services to Users of JASMIN for Environmental Data Analysis
Providing Globus Services to Users of JASMIN for Environmental Data Analysis
Globus
 
Paketo Buildpacks : la meilleure façon de construire des images OCI? DevopsDa...
Paketo Buildpacks : la meilleure façon de construire des images OCI? DevopsDa...Paketo Buildpacks : la meilleure façon de construire des images OCI? DevopsDa...
Paketo Buildpacks : la meilleure façon de construire des images OCI? DevopsDa...
Anthony Dahanne
 
Corporate Management | Session 3 of 3 | Tendenci AMS
Corporate Management | Session 3 of 3 | Tendenci AMSCorporate Management | Session 3 of 3 | Tendenci AMS
Corporate Management | Session 3 of 3 | Tendenci AMS
Tendenci - The Open Source AMS (Association Management Software)
 
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERRORTROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
Tier1 app
 
Why React Native as a Strategic Advantage for Startup Innovation.pdf
Why React Native as a Strategic Advantage for Startup Innovation.pdfWhy React Native as a Strategic Advantage for Startup Innovation.pdf
Why React Native as a Strategic Advantage for Startup Innovation.pdf
ayushiqss
 
Visitor Management System in India- Vizman.app
Visitor Management System in India- Vizman.appVisitor Management System in India- Vizman.app
Visitor Management System in India- Vizman.app
NaapbooksPrivateLimi
 

Recently uploaded (20)

Understanding Globus Data Transfers with NetSage
Understanding Globus Data Transfers with NetSageUnderstanding Globus Data Transfers with NetSage
Understanding Globus Data Transfers with NetSage
 
BoxLang: Review our Visionary Licenses of 2024
BoxLang: Review our Visionary Licenses of 2024BoxLang: Review our Visionary Licenses of 2024
BoxLang: Review our Visionary Licenses of 2024
 
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
Multiple Your Crypto Portfolio with the Innovative Features of Advanced Crypt...
 
Prosigns: Transforming Business with Tailored Technology Solutions
Prosigns: Transforming Business with Tailored Technology SolutionsProsigns: Transforming Business with Tailored Technology Solutions
Prosigns: Transforming Business with Tailored Technology Solutions
 
GlobusWorld 2024 Opening Keynote session
GlobusWorld 2024 Opening Keynote sessionGlobusWorld 2024 Opening Keynote session
GlobusWorld 2024 Opening Keynote session
 
Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus Compute wth IRI Workflows - GlobusWorld 2024Globus Compute wth IRI Workflows - GlobusWorld 2024
Globus Compute wth IRI Workflows - GlobusWorld 2024
 
Globus Connect Server Deep Dive - GlobusWorld 2024
Globus Connect Server Deep Dive - GlobusWorld 2024Globus Connect Server Deep Dive - GlobusWorld 2024
Globus Connect Server Deep Dive - GlobusWorld 2024
 
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
Climate Science Flows: Enabling Petabyte-Scale Climate Analysis with the Eart...
 
Lecture 1 Introduction to games development
Lecture 1 Introduction to games developmentLecture 1 Introduction to games development
Lecture 1 Introduction to games development
 
Strategies for Successful Data Migration Tools.pptx
Strategies for Successful Data Migration Tools.pptxStrategies for Successful Data Migration Tools.pptx
Strategies for Successful Data Migration Tools.pptx
 
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
How Does XfilesPro Ensure Security While Sharing Documents in Salesforce?
 
First Steps with Globus Compute Multi-User Endpoints
First Steps with Globus Compute Multi-User EndpointsFirst Steps with Globus Compute Multi-User Endpoints
First Steps with Globus Compute Multi-User Endpoints
 
De mooiste recreatieve routes ontdekken met RouteYou en FME
De mooiste recreatieve routes ontdekken met RouteYou en FMEDe mooiste recreatieve routes ontdekken met RouteYou en FME
De mooiste recreatieve routes ontdekken met RouteYou en FME
 
OpenFOAM solver for Helmholtz equation, helmholtzFoam / helmholtzBubbleFoam
OpenFOAM solver for Helmholtz equation, helmholtzFoam / helmholtzBubbleFoamOpenFOAM solver for Helmholtz equation, helmholtzFoam / helmholtzBubbleFoam
OpenFOAM solver for Helmholtz equation, helmholtzFoam / helmholtzBubbleFoam
 
Providing Globus Services to Users of JASMIN for Environmental Data Analysis
Providing Globus Services to Users of JASMIN for Environmental Data AnalysisProviding Globus Services to Users of JASMIN for Environmental Data Analysis
Providing Globus Services to Users of JASMIN for Environmental Data Analysis
 
Paketo Buildpacks : la meilleure façon de construire des images OCI? DevopsDa...
Paketo Buildpacks : la meilleure façon de construire des images OCI? DevopsDa...Paketo Buildpacks : la meilleure façon de construire des images OCI? DevopsDa...
Paketo Buildpacks : la meilleure façon de construire des images OCI? DevopsDa...
 
Corporate Management | Session 3 of 3 | Tendenci AMS
Corporate Management | Session 3 of 3 | Tendenci AMSCorporate Management | Session 3 of 3 | Tendenci AMS
Corporate Management | Session 3 of 3 | Tendenci AMS
 
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERRORTROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
TROUBLESHOOTING 9 TYPES OF OUTOFMEMORYERROR
 
Why React Native as a Strategic Advantage for Startup Innovation.pdf
Why React Native as a Strategic Advantage for Startup Innovation.pdfWhy React Native as a Strategic Advantage for Startup Innovation.pdf
Why React Native as a Strategic Advantage for Startup Innovation.pdf
 
Visitor Management System in India- Vizman.app
Visitor Management System in India- Vizman.appVisitor Management System in India- Vizman.app
Visitor Management System in India- Vizman.app
 

JOSA TechTalks - RESTful API Concepts and Best Practices

  • 1. RESTFUL API CONCEPTS AND BEST PRACTICES Yazan Qutieshat Tambi Jalouqa Senior Software Engineer at Souq.com a subsidiary of amazon Head of Products at Propeller inc.
  • 2. Working on a social media aggregator opened my eyes to many restful APIs such as (Facebook, Twitter, Instagram…) How i used to create API’s `GET /getComments/` [Get Comments] `POST /addComment/` [Add a Comment] `POST /deleteComment/` [Delete a Comment] MY STORY How Facebook API's work `GET /posts/{post_id}/comments` [Get Comments] `POST /posts/{post_id}/comments` [Add a Comment]
 `DELETE /comments/{comment_id}` [Delete a Comment]
  • 3. RESTFUL ARCHITECTURE WHAT MAKES AN API RESTFUL Representational state transfer (REST) or RESTful web services is a way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations.
  • 4. RESTFUL ARCHITECTURE WHAT MAKES AN API RESTFUL REST is the underlying architectural principle of the web. The amazing thing about the web is the fact that clients and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts.
  • 6. THE SIMPLE VERSION A set of guidelines (attributes and characteristic) that aims to design a single interface that reflect your business to all your consumers while being stateless and readable.
  • 7. WHAT MAKES AN API RESTFUL The main ingredients of a Restful Api • Resources • Protocol (Http) • Headers • Methods • Status Codes The Guidelines
  • 8. WHAT MAKES AN API RESTFUL Resources : Any abstraction of information that has a meaning in your domain (business) The Guidelines • Virtual object. • Singleton or a Collection • List of available options. • Result of a mathematical operation.
  • 9. WHAT MAKES AN API RESTFUL Protocol (HTTP) : Methods : Use Methods to Retrieve and Manipulate (Creation, Mutation) resources. The Guidelines • GET [Retrieve] : Safe, Idempotent , Cacheable • PUT [update] : Idempotent • DELETE [delete]: Idempotent • PATCH [Partial update] : Idempotent • POST [Create]
  • 10. WHAT MAKES AN API RESTFUL Protocol (HTTP) : Status Codes : Use Status Codes to inform how client how he should proceed. The Guidelines • Successful 2xx (200 Successful, 201 Created, 204 No Content) • Multiple choices 3xx (301 Moved, 302 Found, 304 Not Modified) • User Errors 4xx (401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity ) • Server Errors 5xx
  • 12. THE ALTERNATIVES RPC Remote Procedure Call (RPC) is a protocol that one program can use to request a service from a program located in another computer on a network without having to understand the network's details. A procedure call is also sometimes known as a function call or a subroutine call • Complicated • Lacks consistency • Oriented around procedures
  • 13. THE ALTERNATIVES SOAP It is method for exchanging XML based message over the Internet for providing and consuming web services. SOAP message are transferred forming the SOAP-Envelope. • Rigid • Requires Development • Requires Knowledge
  • 14. THE ALTERNATIVES GRAPH QL Instead of working with rigid server-defined endpoints, you can send queries to get exactly the data you’re looking for in one request • Still Young • Requires domain knowledge • Coupled with the backend
  • 15. BENEFITS • Simple • Scalable • Cacheable • Testable
  • 16. REINVENTING THE WHEEL Authentication (Basic, OAuth, JWT) Security (ACL, CORS) Traffic control (Rate Limiting, Termination) Logging
  • 17. TOOLS
  • 23. THANK YOU END OF PART ONE
  • 25. API FIRST DEVELOPMENT Lets start with a story about a mountain bike trail
  • 26. I LOVE MOUNTAIN BIKING AND THATS WHY I BUILD TRAILS
  • 27. BUT BUILDING TRAILS IS HARD AND REQUIRES TRAIL DESIGN
  • 28. HEAVY MACHINERY COMES LAST. MARKING WITH STICK AND STONE IS FIRST
  • 29. SKETCHING VS PIXEL PERFECT DESIGN • Include the team • Allow change to happen • Faster feedback loop
  • 30. TREAT YOUR API LIKE A CONSUMER PRODUCT Consumers of your API should be treated as if they are going to pay for it. Do not take them for granted. They will either move on or have a bad experience.
  • 32. USER EXPERIENCE Using the proper language while naming your endpoints and resources will help users understand how to use your API. Using nouns vs verbs helps set the mental model for using the API. COMMUNICATE PROPERLY Use
 POST /people Instead of 
 POST /addPerson
  • 33. Be consistent in your return status codes. Try to use a few but well understood status codes such as 200, 201, 403 Do not re-define status codes in a way that will confuse users. Returning a 201 when a resource is edited will confuse the user and increase cognitive load. BE FAMILIAR USER EXPERIENCE
  • 34. Be clear about the wrong ways of using your API. If you require a certain schema return an error that is descriptive of what is the issue. Invalid keys, invalid datatypes, required fields that are empty. You will make solving issues while using the API much faster if you are clear and helpful. ALWAYS GIVE USEFUL FEEDBACK USER EXPERIENCE
  • 35. Always return the same schema or status code for the same operations if possible This will help users re-use their learned behavior For example they can create an abstraction around using your API BE CONSISTENT USER EXPERIENCE
  • 36. Implement a consistent pagination, filtering or relations in your API Different users will have different needs. One user might want the whole collection while another will only need a few pages. Mobile clients would try to be bandwidth conservative and only ask for what they need. DESIGN FOR DIFFERENT USE 
 GET /people?fields=firstname,lastname&limit=10&skip=3 USER EXPERIENCE
  • 37. HELP USERS BE SMARTER USER EXPERIENCE
  • 38. HELP USERS BE SMARTER Specify the life of your returned results. Add meta data to allow smart users to cache your data to reduce chatter and allow for offline experiences. Use ETag or Last-Modified to allow users to know if a resource has been updated and they will receive fresh data from your API USER EXPERIENCE
  • 39. USER EXPERIENCE BE BACKWARDS COMPATIBLE Versioning your api will allow for users that have not updated their code to continue interacting with your API This allows for an incremental move to a newer version on their own paces. But always give them a push toward newer better versions. Available options are URI based versioning or the Accept header or custom request headers.
  • 40.
  • 42. Many times API designers tend to crudify their APIs Always think about each resource and how it fits your domain. Sometimes a resource will only allow for creating a new resource and not editing it. ALWAYS USING CRUD COMMON PITFALLS e.g. financial transactions
 POST /transactions Transactions will not accept PUT, PATCH, DELETE
  • 43. Changes to an API that will break existing clients need to be clear. If the interface changes underneath without them knowing it systems will break. As discussed before always increment the available version and help onboard users to the newer API Always communicate upcoming changes and create the proper channels to facilitate that NOT USING VERSIONING COMMON PITFALLS
  • 44. COMMON PITFALLS Designing an API without the proper feedback loop will guarantee that your API is not usable. Not taking the users into consideration will create an API that is not user-centered and will require a re-design for new use cases. NOT INCLUDING YOUR STAKEHOLDERS
  • 45. COMMON PITFALLS Use industry standards to document your API, Swagger, Blueprint, RAML, etc. Having the users to either ask for the schema or read through your code to understand usage of your API is a recipe for disaster. NOT DOCUMENTING
  • 46. ALWAYS BE DESIGNING THE API IS A CONSUMER FACING PRODUCT, TREAT THEM THAT WAY.
  • 47. THANK YOU END OF PART TWO
  • 48. Q&A Yazan Qutieshat Tambi Jalouqa Senior Software Engineer at Souq.com a subsidiary of amazon
 yazan.qutieshat@gmail.com Head of Products at Propeller inc. 
 tambi@propellerinc.me