usable rest apis, by javier ramirez from teowaki (apidays mediterranea)
DESCRIPTION
How you can make your REST API more usable. Lessons learnt while developing https://teowaki.comTRANSCRIPT
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