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
![Page 1: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/1.jpg)
usableusable REST REST APIsAPIs
{ "_links":{ "author": {"href":"http://javier-ramirez.com"}, "work": {"href":"http://teowaki.com"}, "twitter": {"href":"http//twitter.com/supercoco9"}
} }
![Page 2: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/2.jpg)
Bedale, North of England
![Page 3: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/3.jpg)
a randompostbox in Bedale
![Page 4: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/4.jpg)
a usabilityproblem
![Page 5: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/5.jpg)
everybody agrees web usabilityis a good investment
![Page 6: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/6.jpg)
API usability? meh
http://docs.aws.amazon.com/AWSECommerceService/2011-08-01/DG/rest-signature.html
![Page 7: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/7.jpg)
![Page 8: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/8.jpg)
![Page 9: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/9.jpg)
![Page 10: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/10.jpg)
![Page 11: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/11.jpg)
![Page 12: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/12.jpg)
![Page 13: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/13.jpg)
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.
![Page 14: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/14.jpg)
LearnabilityEfficiencyMemorabilityErrorsSatisfaction
Usability 101, the 5 quality components by Jakob Nielsen
![Page 15: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/15.jpg)
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
![Page 16: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/16.jpg)
Succeed consistently
Fail consistently
![Page 17: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/17.jpg)
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
![Page 18: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/18.jpg)
speed or at least asynchronous operations
![Page 19: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/19.jpg)
different users
different nerds needs
![Page 20: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/20.jpg)
netflix REST apiresource based
![Page 21: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/21.jpg)
netflix REST apiexperience based
http://www.slideshare.net/danieljacobson/api-revolutions-16755403
![Page 22: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/22.jpg)
all your format
are belong to us
*even native formats
![Page 23: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/23.jpg)
formats
![Page 24: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/24.jpg)
CORS: Cross origin resource sharing
![Page 25: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/25.jpg)
Don't expose your implementations details Resources are not models
![Page 26: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/26.jpg)
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
![Page 27: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/27.jpg)
REST
![Page 28: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/28.jpg)
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
![Page 29: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/29.jpg)
Hypermedia
Navigable APIsAssociated resourcesNext stepsPagination
Versioning
![Page 30: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/30.jpg)
HAL:HypermediaApplicationLanguage
extra ball => http://stedolan.github.io/jq/
![Page 31: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/31.jpg)
empty new resources> curl “https://api.teowaki.com/teams/5677-dev”
![Page 32: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/32.jpg)
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))
![Page 33: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/33.jpg)
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
![Page 34: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/34.jpg)
![Page 35: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/35.jpg)
![Page 36: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/36.jpg)
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
![Page 37: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/37.jpg)
don't let your APIbe the poobox whereyour userspost theirrequests
Moral of this talk
![Page 38: Usable REST APIs. Jrubyconf Edition. Javier Ramirez @ teowaki](https://reader033.vdocuments.us/reader033/viewer/2022060108/554f4a01b4c905b9508b47df/html5/thumbnails/38.jpg)
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