USABLE REST APIs
{ "_links":{
"author": {"href":"http://javier-ramirez.com"},
"work": {"href":"https://teowaki.com"},
"twi...
Bedale, North of England
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/2011-08-01/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...
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
netflix REST api
resource based
netflix REST api
experience based

http://www.slideshare.net/danieljacobson/api-revolutions-16755403
all your
format
are belong
to us
*even native formats
formats
CORS: Cross origin
resource sharing
Don't expose your implementations details
Resources are not models
Easier to understand
Change the internals
without breaking the
contract
Resources based on
business objects are
more resis...
REST
REST Highlights you should know
about but not necessarily implement
client-server,stateless,layered,cacheable
Resources
Re...
Hypermedia

Navigable APIs
API pagination
API links
-----Next
steps
Several resources in a single request
Versioning
without
versions
HAL:
Hypermedia
Application
Language

extra ball => http://stedolan.github.io/jq/
empty new resources
> curl “https://api.teowaki.com/teams/5677-dev”
Partial Responses
teowaki's approach
api.teowaki.com/people/tw?api_quiet=true&api_links=false

Google's approach
www.googl...
Where to put your metadata
In your HTTP Headers?
As request params and response fields?
Both?

Don't worry too much. Just ...
Don't just implement. Think
Should the API allow asynchronous creation, update
and deletion? => return-async
Should it ret...
don't let
your API
be the poo
box where
your users
post their
requests
Moral of this talk
Shameless self promotion
If you enjoyed this presentation, please thank me by
registering on https://teowaki.com
It's a si...
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Usable REST APIs. BCNdevcon edition.
Upcoming SlideShare
Loading in …5
×

Usable REST APIs. BCNdevcon edition.

3,627 views

Published on

With the adoption of REST, the proliferation of smartphones and tablets, and the second coming of JavaScript, exposing our applications as a service is now more important than ever.

Lots of libraries and frameworks make really easy to create a (kinda) RESTful API but, in many occassions, these APIs are designed without really thinking on the developers that will have to use them.

I want to talk about some of the points that can help making your API more developer-friendly. Some of the areas I’ll cover will be discoverability, authentication, headers, formats, parameters, documentation and tools.

Published in: Technology, Design
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
3,627
On SlideShare
0
From Embeds
0
Number of Embeds
23
Actions
Shares
0
Downloads
9
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

Usable REST APIs. BCNdevcon edition.

  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 of England
  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/2011-08-01/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. Succeed consistently Fail consistently
  11. 11. 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 huddle 200 OK 201 Created 202 Accepted 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 410 Gone teowaki 200 OK Success! 201 Created 304 Not Modified 401 Unauthorized 403 Forbidden 404 Not Found 422 Unprocessable Entity 406 Not Acceptable 500 Internal Server Error
  12. 12. speed or at least asynchronous operations
  13. 13. different users different nerds needs
  14. 14. netflix REST api resource based
  15. 15. netflix REST api experience based http://www.slideshare.net/danieljacobson/api-revolutions-16755403
  16. 16. all your format are belong to us *even native formats
  17. 17. formats
  18. 18. CORS: Cross origin resource sharing
  19. 19. Don't expose your implementations details Resources are not models
  20. 20. 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
  21. 21. REST
  22. 22. 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
  23. 23. Hypermedia Navigable APIs
  24. 24. API pagination
  25. 25. API links -----Next steps
  26. 26. Several resources in a single request
  27. 27. Versioning without versions
  28. 28. HAL: Hypermedia Application Language extra ball => http://stedolan.github.io/jq/
  29. 29. empty new resources > curl “https://api.teowaki.com/teams/5677-dev”
  30. 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. 31. 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
  32. 32. 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
  33. 33. don't let your API be the poo box where your users post their requests Moral of this talk
  34. 34. Shameless self promotion If you enjoyed this presentation, please thank me by registering on https://teowaki.com It's a site for developers, you can hang around for free, and I think it's quite cool (but a bit buggy since we've just launched) <3 <3 <3 Javier Ramírez @supercoco9

×