This document provides information on creating usable REST APIs. It discusses principles like following best practices, making APIs learnable and efficient for users, and avoiding exposing implementation details. The document also provides examples of API design choices around topics like versioning, pagination, and allowing asynchronous operations. It emphasizes that there are no single right answers and each API has different needs, so copying approaches from other projects without thought is the wrong approach. The overall message is to thoughtfully design APIs around usability and the needs of developers using the API.

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 Yorkshire

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/latest/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. don't be too smart
follow best practices

19. Succeed consistently
Fail consistently

20. twitter
200 OK Success!
304 Not Modified
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
406 Not Acceptable
410 Gone
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

21. speed
or at least asynchronous operations

22. different users
different nerds needs

23. Javi, you are
not an example
of anything

24. formats

25. CORS: Cross origin
resource sharing

26. Where to put your metadata
In your HTTP Headers?
As request params and response fields?
Maybe Both? It usually pays not to be
too strict and just make your users' lives
easier

29. Same content?

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

31. netflix REST api
resource based

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

33. Don't expose your implementations details
Resources are not database tables

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

35. I shouldn't be able
to guess your
programming language
by looking at your API

36. Hypermedia
Navigable APIs

37. API pagination

38. HAL:
Hypermedia
Application
Language

39. JSON-API

40. API links
------
Next
steps

41. Several resources in a single request

42. Versioning
without
versions

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

44. URI templates
http://example.com/~{username}/
http://example.com/dictionary/{term:1}/{term}
http://example.com/search{?q,lang}

45. self-documented
API

47. Swagger

48. Swagger

49. RAML

50. RAML

51. Don't just
implement.
Think

52. Should my API allow
asynchronous creation,
update,
and deletion?

53. Should it return the
contents of a newly created
or updated resource or
just the id?
What about deleted
resources?

54. Should my API ignore
unrecognised parameters
silently, even when it is getting
a valid request, or should it
return an error?

55. Should it allow
bulk operations?
PATCH /users/541,1001,3005

56. Does my API need a real-time
or push mechanism
for updates?
Do I need to set usage quotas?

57. There are not good or bad
answers. Each API has
different needs.
The only wrong answer is
copying and pasting from
your last project and
pretend the work is done.

58. Learnability
Efficiency
Memorability
Errors
Satisfaction
Remember:

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

60. Find related links at
https://teowaki.com/teams/javier-community/link-categories/apis
Thanks!
Javier Ramírez
@supercoco9