JOSA TechTalks - RESTful API Concepts and Best Practices
4 likes578 views
The document outlines key concepts and best practices for designing RESTful APIs, emphasizing the importance of a stateless architecture and standard HTTP methods. It discusses the main ingredients of a REST API, such as resources, protocols, and status codes, and contrasts REST with alternatives like SOAP and GraphQL. Best practices include treating APIs like consumer products, ensuring user experience through consistent naming and response handling, and maintaining backward compatibility through versioning.
![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]](https://image.slidesharecdn.com/restfulapiconcepts-170820202616/85/JOSA-TechTalks-RESTful-API-Concepts-and-Best-Practices-2-320.jpg)
![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]](https://image.slidesharecdn.com/restfulapiconcepts-170820202616/85/JOSA-TechTalks-RESTful-API-Concepts-and-Best-Practices-9-320.jpg)
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
- 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 [email protected] Head of Products at Propeller inc. [email protected]