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

SOAPRPC

GRAPH

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

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 YOUEND 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 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.

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 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

ALWAYS BE DESIGNINGTHE API IS A CONSUMER FACING PRODUCT, TREAT THEM THAT WAY.

THANK YOUEND 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