View
274
Download
1
Embed Size (px)
Citation preview
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.
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 ALTERNATIVESRPCRemote 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 ALTERNATIVESSOAPIt 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 ALTERNATIVESGRAPH QLInstead 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
REINVENTING THE WHEEL
Authentication (Basic, OAuth, JWT)
Security (ACL, CORS)
Traffic control (Rate Limiting, Termination)
Logging
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
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
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 EXPERIENCEBE 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.
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 transactionsPOST /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
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]