How you can make your REST API more usable. Lessons learnt while developing https://teowaki.com

1. USABLE
REST APIs
{ "_links":{
"author": {"href":"http://javier-ramirez.com"},
"work": {"href":"https://teowaki.com"},
"twitter": {"href":"https://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

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

18. Succeed consistently
Fail consistently

19. 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
202 Accepted
301 Moved Permanently
304 Not Modified
401 Unauthorized
403 Forbidden
404 Not Found
406 Not Acceptable
422 Unprocessable Entity
406 Not Acceptable
500 Internal Server Error

20. speed
or at least asynchronous operations

21. different users
different nerds needs

22. netflix REST api
resource based

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

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

25. formats

26. CORS: Cross origin
resource sharing

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

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

29. REST

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

31. Hypermedia
Navigable APIs

32. API pagination

33. API links
------
Next
steps

34. Several resources in a single request

35. Versioning
without
versions

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

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

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

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

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

43. self-documented
API

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

46. Find related links at
https://teowaki.com/teams/javier-community/link-categories/apis
Thanks!
Gr ciesà
Javier Ramírez
@supercoco9
rubyc kiev 14