How you can make your REST APIs more usables with a brief introduction to hypermedia. Talk delivered at Jrubyconf EU 2013

1. usableusable RESTREST
APIsAPIs
{ "_links":{
"author": {"href":"http://javier-ramirez.com"},
"work": {"href":"http://teowaki.com"},
"twitter": {"href":"http//twitter.com/supercoco9"}
} }

2. Bedale, North of England

3. a random
postbox
in Bedale

4. a usability
problem

5. everybody agrees web usability
is a good investment

6. API usability? meh
http://docs.aws.amazon.com/AWSECommerceService/2011-08-01/DG/rest-signature.html

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

14. Learnability
Efficiency
Memorability
Errors
Satisfaction
Usability 101, the 5 quality components by Jakob Nielsen

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

16. Succeed consistently
Fail consistently

17. huddle
200 OK
201 Created
202 Accepted
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
410 Gone
twitter
200 OK Success!
304 Not Modified
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
406 Not Acceptable
420 Enhance Your Calm
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
Useful Status
429 Too many requests
204 No Content
teowaki
200 OK Success!
201 Created
304 Not Modified
401 Unauthorized
404 Not Found
422 Unprocessable Entity
406 Not Acceptable
500 Internal Server Error

18. speed
or at least asynchronous operations

19. different users
different nerds needs

20. netflix REST api
resource based

21. netflix REST api
experience based
http://www.slideshare.net/danieljacobson/api-revolutions-16755403

22. all your
format
are belong
to us
*even native formats

23. formats

24. CORS: Cross origin
resource sharing

25. Don't expose your implementations details
Resources are not models

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

27. REST

28. REST Highlights you should know
about but not necessarily implement
client-server,stateless,layered,cacheable
Resources
Resource Identifiers
Resource metadata
Uniform interface
operations
Representations
Representation metadata
HATEOAS (Hypermedia)
Optionally: code on demand

29. Hypermedia
Navigable APIs
Associated resources
Next steps
Pagination
Versioning

30. HAL:
Hypermedia
Application
Language
extra ball => http://stedolan.github.io/jq/

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

32. 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))

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

36. Don't just implement. Think
Should 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

37. don't let
your API
be the poo
box where
your users
post their
requests
Moral of this talk

38. 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 <3
Javier Ramírez
@supercoco9