O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.
USABLE
REST APIs
{ "_links":{
"author": {"href":"http://javier-ramirez.com"},
"work": {"href":"https://teowaki.com"},
"twi...
Bedale, North Yorkshire
a random
postbox
in Bedale
a usability
problem
everybody agrees web usability is a good
investment
API usability? meh
http://docs.aws.amazon.com/AWSECommerceService/latest/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 t...
Learnability
Efficiency
Memorability
Errors
Satisfaction
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 mus...
don't be too smart
follow best practices
Succeed consistently
Fail consistently
twitter
200 OK Success!
304 Not Modified
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
406 Not Acceptable
4...
speed
or at least asynchronous operations
different users
different nerds needs
Javi, you are
not an example
of anything
formats
CORS: Cross origin
resource sharing
Where to put your metadata
In your HTTP Headers?
As request params and response fields?
Maybe Both? It usually pays not to...
Same content?
Partial Responses
teowaki's approach
api.teowaki.com/people/tw?api_quiet=true&api_links=false
Google's approach
www.google...
netflix REST api
resource based
netflix REST api
experience based
http://www.slideshare.net/danieljacobson/api-revolutions-16755403
Don't expose your implementations details
Resources are not database tables
Easier to understand
Change the internals
without breaking the
contract
Resources based on
business objects are
more resis...
I shouldn't be able
to guess your
programming language
by looking at your API
Hypermedia
Navigable APIs
API pagination
HAL:
Hypermedia
Application
Language
JSON-API
API links
------
Next
steps
Several resources in a single request
Versioning
without
versions
empty new resources
> curl “https://api.teowaki.com/teams/5677-dev”
URI templates
http://example.com/~{username}/
http://example.com/dictionary/{term:1}/{term}
http://example.com/search{?q,l...
self-documented
API
Swagger
Swagger
RAML
RAML
Don't just
implement.
Think
Should my API allow
asynchronous creation,
update,
and deletion?
Should it return the
contents of a newly created
or updated resource or
just the id?
What about deleted
resources?
Should my API ignore
unrecognised parameters
silently, even when it is getting
a valid request, or should it
return an err...
Should it allow
bulk operations?
PATCH /users/541,1001,3005
Does my API need a real-time
or push mechanism
for updates?
Do I need to set usage quotas?
There are not good or bad
answers. Each API has
different needs.
The only wrong answer is
copying and pasting from
your la...
Learnability
Efficiency
Memorability
Errors
Satisfaction
Remember:
don't let
your API
be the poo
box where
your users
post their
requests
Moral of this talk
Find related links at
https://teowaki.com/teams/javier-community/link-categories/apis
Thanks!
Javier Ramírez
@supercoco9
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London
Próximos SlideShares
Carregando em…5
×

Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London

823 visualizações

Publicada em

How to build restful apis with a good developer experience. Presented at FOWA London 2015.

Publicada em: Engenharia
  • Seja o primeiro a comentar

Building Usable REST APIs. By Javier Ramirez, teowaki. FOWA London

  1. 1. USABLE REST APIs { "_links":{ "author": {"href":"http://javier-ramirez.com"}, "work": {"href":"https://teowaki.com"}, "twitter": {"href":"https://twitter.com/supercoco9"} } }
  2. 2. Bedale, North Yorkshire
  3. 3. a random postbox in Bedale
  4. 4. a usability problem
  5. 5. everybody agrees web usability is a good investment
  6. 6. API usability? meh http://docs.aws.amazon.com/AWSECommerceService/latest/DG/rest-signature.html
  7. 7. 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.
  8. 8. Learnability Efficiency Memorability Errors Satisfaction Usability 101, the 5 quality components by Jakob Nielsen
  9. 9. 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
  10. 10. don't be too smart follow best practices
  11. 11. Succeed consistently Fail consistently
  12. 12. 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
  13. 13. speed or at least asynchronous operations
  14. 14. different users different nerds needs
  15. 15. Javi, you are not an example of anything
  16. 16. formats
  17. 17. CORS: Cross origin resource sharing
  18. 18. 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
  19. 19. Same content?
  20. 20. 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))
  21. 21. netflix REST api resource based
  22. 22. netflix REST api experience based http://www.slideshare.net/danieljacobson/api-revolutions-16755403
  23. 23. Don't expose your implementations details Resources are not database tables
  24. 24. 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
  25. 25. I shouldn't be able to guess your programming language by looking at your API
  26. 26. Hypermedia Navigable APIs
  27. 27. API pagination
  28. 28. HAL: Hypermedia Application Language
  29. 29. JSON-API
  30. 30. API links ------ Next steps
  31. 31. Several resources in a single request
  32. 32. Versioning without versions
  33. 33. empty new resources > curl “https://api.teowaki.com/teams/5677-dev”
  34. 34. URI templates http://example.com/~{username}/ http://example.com/dictionary/{term:1}/{term} http://example.com/search{?q,lang}
  35. 35. self-documented API
  36. 36. Swagger
  37. 37. Swagger
  38. 38. RAML
  39. 39. RAML
  40. 40. Don't just implement. Think
  41. 41. Should my API allow asynchronous creation, update, and deletion?
  42. 42. Should it return the contents of a newly created or updated resource or just the id? What about deleted resources?
  43. 43. Should my API ignore unrecognised parameters silently, even when it is getting a valid request, or should it return an error?
  44. 44. Should it allow bulk operations? PATCH /users/541,1001,3005
  45. 45. Does my API need a real-time or push mechanism for updates? Do I need to set usage quotas?
  46. 46. 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.
  47. 47. Learnability Efficiency Memorability Errors Satisfaction Remember:
  48. 48. don't let your API be the poo box where your users post their requests Moral of this talk
  49. 49. Find related links at https://teowaki.com/teams/javier-community/link-categories/apis Thanks! Javier Ramírez @supercoco9

×