usable rest apis. jrubyconf edition. javier ramirez @ teowaki
DESCRIPTION
How you can make your REST APIs more usables with a brief introduction to hypermedia. Talk delivered at Jrubyconf EU 2013TRANSCRIPT
usableusable REST REST APIsAPIs
{ "_links":{ "author": {"href":"http://javier-ramirez.com"}, "work": {"href":"http://teowaki.com"}, "twitter": {"href":"http//twitter.com/supercoco9"}
} }
Bedale, North of England
a randompostbox in Bedale
a usabilityproblem
everybody agrees web usabilityis 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
huddle200 OK 201 Created202 Accepted400 Bad Request401 Unauthorized403 Forbidden404 Not Found410 Gone
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 Created304 Not Modified401 Unauthorized404 Not Found422 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 APIsAssociated resourcesNext stepsPagination
Versioning
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
don't let your APIbe the poobox whereyour userspost theirrequests
Moral of this talk
Shameless self promotion If you enjoyed this presentation, please thank me by
registering on http://teowaki.com
It's a site for developers, you can hang around for free, and I think it's quite cool
<3 <3 <3Javier Ramírez
@supercoco9