usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)

USABLE REST APIs

{ "_links":{ "author": {"href":"http://javier-ramirez.com"}, "work": {"href":"https://teowaki.com"}, "twitter": {"href":"https://twitter.com/supercoco9"}

} }

Bedale, North of England

a randompostbox in Bedale

a usabilityproblem

everybody agrees web usability is a good investment

API usability? meh

http://docs.aws.amazon.com/AWSECommerceService/2011-08-01/DG/rest-signature.html

Web usability is an approach to make web sites

easy to use for an end-user, without the requirement that any specialized training be

undertaken.

LearnabilityEfficiencyMemorabilityErrorsSatisfaction

Usability 101, the 5 quality components by Jakob Nielsen

EFFECTIVE IMMEDIATELY!! NO MORE TYPEWRITERS ARE TO BE PURCHASED, LEASED, etc., etc. Apple is an innovative company. We must believe and lead in all areas. If word processing is so neat, then let's all use it!

Mike Scott, Apple President, 1980

Succeed consistently

Fail consistently

twitter200 OK Success!304 Not Modified400 Bad Request401 Unauthorized403 Forbidden404 Not Found406 Not Acceptable420 Enhance Your Calm500 Internal Server Error502 Bad Gateway503 Service Unavailable

Useful Status429 Too many requests204 No Content

teowaki200 OK Success!201 Created202 Accepted301 Moved Permanently304 Not Modified401 Unauthorized403 Forbidden404 Not Found406 Not Acceptable422 Unprocessable Entity406 Not Acceptable500 Internal Server Error

speed or at least asynchronous operations

different users

different nerds needs

netflix REST apiresource based

netflix REST apiexperience based

http://www.slideshare.net/danieljacobson/api-revolutions-16755403

all your format

are belong to us

*even native formats

formats

CORS: Cross origin resource sharing

Don't expose your implementations details Resources are not models

Easier to understand

Change the internals without breaking the contract

Resources based on business objects are more resistant to versioning

More opacity means more security

REST

REST Highlights you should know about but not necessarily implement

client-server,stateless,layered,cacheable Resources

Resource IdentifiersResource metadata

Uniform interfaceoperationsRepresentationsRepresentation metadata

HATEOAS (Hypermedia)Optionally: code on demand

Hypermedia

Navigable APIs

API pagination

API links------Next steps

Several resources in a single request

Versioning without versions

HAL:HypermediaApplicationLanguage

extra ball => http://stedolan.github.io/jq/

empty new resources> curl “https://api.teowaki.com/teams/5677-dev”

Partial Responses

teowaki's approach

api.teowaki.com/people/tw?api_quiet=true&api_links=false

Google's approach

www.googleapis.com/youtube/v3/videos?part=snippet&fields=items(id,snippet(title,position))

Where to put your metadata In your HTTP Headers?

As request params and response fields?

Both?

Don't worry too much. Just choose one and stick to it

Don't just implement. ThinkShould the API allow asynchronous creation, update and deletion? => return-async

Should it return the created/deleted/updated object or just a status code? =>return-representation

Should it ignore extra params transparently or should it warn you? => api_strict_mode

Should it allow for bulk updates/deletions on collections? => PATCH /user/links

Think of your own questions. There are not good or bad answers

self-documentedAPI

don't let your APIbe the poobox whereyour userspost theirrequests

Moral of this talk

Find related links at

https://teowaki.com/teams/javier-community/link-categories/apis

Thanks!Gr ciesà

Javier Ramírez@supercoco9

rubyc kiev 14