Everyday we create services for our systems. A lot of people create RESTful APIs but much more can be accomplished by following best practices and treating your APIs as a product to be consumed by fellow team members, systems and 3rd party consumers. We will discuss what makes a great RESTful API and share some of our experiences building some that power real systems. This was part of JOSA TechTalks project within Jordan Open Source Association, presented by Yazan Quteishat and Tambi Jalouqa.

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.

5. ARCHITECTURAL STYLE

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

11. THE ALTERNATIVES
SOAP
RPC
GRAPH

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

18. TOOLS
Word Documents
DOCUMENTATION

19. TOOLS
Apiary (Blueprint)
DOCUMENTATION

20. TOOLS
Swagger
DOCUMENTATION

21. TOOLS
API Gateway AWS
Apigee
Kong
MANAGEMENT

22. TOOLS
Acceptance Testing
Continuous Integration
TESTING

23. THANK YOU
END OF PART ONE

24. BEST PRACTICES FOR
CREATING A RESTFUL
API

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.

31. USER 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.

41. COMMON PITFALLS

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