This document discusses making REST APIs more usable. It provides examples of REST API design principles like using hypermedia to link related resources, returning error responses consistently, and supporting multiple formats and authentication methods. REST APIs should aim to be discoverable, standardized, and usable for both developers and end users.

1. APIs REST Usables
Javier Ramírez
@supercoco9
@aspgems

2. APIs REST
usableS*
edición codemotion.es
{"links":[
{"rel":"author", "uri":"http://javier-ramirez.com"},
{"rel":"work", "uri":"http://aspgems.com"},
{"rel":"twittEr", "uri":"http//twitter.com/supercoco9"}
{"rel":"api-usable", "uri":"https//invoicefu.com"}
]}
*ningún gatico (ni ningún friki ansioso) ha sido dañado para hacer esta presentación

6. 1996

7. 1995

8. 1996

9. 1994

10. 2001

11. La usabilidad Web es un
enfoque para construir
sitios web faciles de usar
'
para un usuario final, sin
que se requiera ninguna
formacion especializada
'

12. Learnability
EfficIeNcy
MemorabiliTy
Errors
SatisfActiOn

14. API “REST”
Hecha con RAILS
en lo que se
TARDA EN decir
constantinopla

16. separation of concerns

17. modelo de
recursos
Autenticación y
(NO) Estado
formatos
Estados y gestión versionado
de errores múltiples
analítica consumidores
monetización paginación
Documentación Escalabilidad
first class api? cuotas
metadatos
… y uSaBiLidAd cachés

18. BASIC ACCESS AUTHENTICATION
authenticate_or_request_with_http_basic do |login, password|
User.find_by_login_and_password login, password
end
User and password must be passed every time
TOKEN
Digest::SHA1.hexdigest( Time.now.to_s.split(//).sort_by {rand}.join )
User.find_by_login_and_api_key( params[:login], params[:api_key] )
Client can send it as a parameter or as a header
OAUTH
Depends on third party libraries
Requires initial registration of client and more integration

19. SUCCESS consistently
fail consistently

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

21. Accept: application/vnd.aspgems.invoicefu.v1.xml
THE
ACCEPT
HEADER
HTTP/REST Standard Not everyone Less obvious
Unambiguous supports headers Harder to use
Resources != or custom types. Non standard content-
Representations Generic content types
Version as you need it types are Skips HTTP server logs
preferred

24. REST explicado por un señor
que tan listo no será cuando
no usa gafas
client-server,stateless,layered,cacheable
Resources
Resource Identifiers
Resource metadata
Uniform interface
operations
Representations
Representation metadata
HATEOAS
Optionally: code on demand señor sin gafas

25. INTERFAZ UNIFORME
get, HEAD, TRACE,
OPTIONS
post, put*, delete*,
PATCH*
*fallbacks para clientes viejos o
incompletos

26. here
be
dragons

27. restfest 2011

28. expose ONLY
WHAT IS
Strictly necessary

29. resources are not models

30. Aggregation/
composition
Multiple
representations

31. Hypermedia
APIs descubribles
Recursos asociados
Siguientes pasos
Paginación

32. https://invoicefu.com?
format=xml

33. curl -X POST "https://invoicefu.com/api/session?
format=xml&login=hello@invoicefu.com&password=YAY
<?xml version="1.0" encoding="UTF-8"?>
<user>
<id>3</id>
<name>javier ramir</name>
<email>javier@formatinternet.com</email>
<locale>es</locale>
<twitter-nickname>supercoco9</twitter-nickname>
<facebook-uid nil="true"></facebook-uid>
<facebook-nickname nil="true"></facebook-nickname>
<api-key>c23e830d9b092a3a801d7f49b46</api-key>
<links>
<link>
<rel>clients</rel>
<uri>https://invoicefu.com/api/accounts/3-javier-ramirez/clients</uri>
<methods>GET,POST</methods>
</link>
<link>
<rel>new_client</rel>
<uri>https://invoicefu.com/api/accounts/3-javier-ramirez/clients/new</uri>
<methods>GET</methods>
</link>

34. Rob Eisenberg
<productions>
<links>
<link rel="self" href="..." />
<link rel="next" href="..." />
</links>
<production>
<name>RavenDB</name>
<author>Oren Eini</author>
<links>
<link rel="self" href="..." />
<link rel="rels/episodes" href="..." />
</links>
</production>
<production>
<name>Art of Speaking</name>
<author>Scott Hanselman</author>
<links>
<link rel="self" href="..." />
<link rel="rels/episodes" href="..." />
</links>
</production>
<!--other productions elided-->
</productions>

35. Mike Kelly
{
"_links": {
"self": { "href": "..." }
},
"title": "Real World ASP.NET MVC3",
"description": "In this advanced, somewhat-opinionated...",
"permitted": true,
"_embedded": {
"episodes": [{
"_links": {
"self": { "href": "..." },
"media": [{
"type": "video/webm; codecs='vp8.0, vorbis'",
"href": "..."
},{
"type": "video/ogg; codecs='theora, vorbis'",
"href": "..."
}]
},
"title": "Foundations",
"description": "In this episode we talk about what it is we're doing: building our
startup and getting ourselves off the ground. We take..",
"released": 1306972800
}

36. DARREL MILLER
{
"_links" : {
"self" : { "href" : "/user/95/allproductions" },
},
"name" : "Joe",
"_embedded" : {
"urn:tekpub:production" : [
{ "_links": {
"self": { "href": "/production/22" },
},
"allowed" : "true",
"title" : "Rails runs rings round ReST resource representations"
},
{ "_links": {
"self": { "href": "/production/74" },
},
"allowed" : "false",
"title" : "Surfing the waves beats surfing an API"
}
]
}
}

37. ACTS AS API :Filtros

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

39. > curl "https://invoicefu.com/api/accounts/108-cole-mertz-fake/invoices/new?
api_key=ddd349b30b6d9fde97b01b827e6be5ed1e4fbe72&format=xml&debug=1"
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>extra params found: debug. Allowed params are:
account_id,client_id,invoice_id,proforma_id</error>
</errors>
> curl "https://invoicefu.com/api/accounts/108-cole-mertz-fake/invoices/new?
api_key=ddd349b30b6d9fde97b01b827e6be5ed1e4fbe72&format=xml&debug=1&strict=false"
<?xml version="1.0" encoding="UTF-8"?>
<invoice>
<number>2011/30</number>
<issued-on>2011-12-11</issued-on>
<proforma-id nil="true"></proforma-id>
(...)
<links>
(...)
<link>
<rel>invoices</rel>
<uri>https://invoicefu-localhost.com/api/accounts/108-cole-mertz-fake/invoices</uri>
<methods>GET,POST</methods>
</link>
</links>
</invoice>

41. templates
for new
resources
> curl "https://invoicefu.com/api/accounts/108-cole-mertz-fake/invoices/new?
api_key=ddd349b30b6d9fde97b027e6be5ed1e4fbe72&format=json"
{"invoice":{"number":"2011/30","issued_on":"2011-12-
12","proforma_id":null,"notes":null,"footer":null,"locale":"en","currency_code":"USD","currency_sym
bol":"$","ac_name":"Cole-Mertz#FAKE","ac_company_number_name":"Company
number","ac_company_number":"25465828K","ac_tax_number_name":"VAT
Number","ac_tax_number":"ES25464828k","ac_address":"234 brecknock
road","ac_city":"london","ac_province":null,"ac_postal_code":"n18 5bq","ac_country_name":"United
Kingdom","cl_email":null,"cl_name":null,"cl_company_number_name":null,"cl_company_number":null,"cl_
tax_number_name":null,"cl_tax_number":null,"cl_address":null,"cl_city":null,"cl_province":null,"cl_
postal_code":null,"cl_country_name":null,"invoice_lines":[],"discount_percent":null,"tax_lines":
[{"name":"TVA","signed_percent":"19.6"}],"paid":"0.0","links":
[{"rel":"payments","uri":"https://invoicefu.com/api/accounts/108-cole-mertz-
fake/invoices//payments","methods":"POST"},
{"rel":"account","uri":"https://invoicefu.com/api/accounts/108-cole-mertz-
fake","methods":"GET,PUT"},{"rel":"client","uri":null,"methods":"GET,PUT,DELETE"},
{"rel":"proforma","uri":null,"methods":"GET,PUT,DELETE"},{"rel":"pdf","uri":null,"methods":"GET"},
{"rel":"invoices","uri":"https://invoicefu.com/api/accounts/108-cole-mertz-
fake/invoices","methods":"GET,POST"}]}}j

42. Multiple consumers

43. All your
FORMAT
are belong
to us
*even native formats

44. javascript revival

45. Cross origin
resource sharing

46. use the
metadata
luke
Permitir cabeceras del tipo
return-async
return-representation
return-minimal
Devolver cabeceras útiles

49. Respuestas parciales
https://gdata.youtube.com/feeds/api/users/default/uploads?
fields=entry(title,gd:comments,yt:statistics)
fields=entry[link/@rel='http://gdata.youtube.com/schemas/20
07%23mobile']

50. Implementación en invoicefu

51. apigee

53. http://usemyapi.com
12 mayo 2012

54. APIs REST
usableS*
edición codemotion.es
{"links":[
{"rel":"author", "uri":"http://javier-ramirez.com"},
{"rel":"work", "uri":"http://aspgems.com"},
{"rel":"blog", "uri":"http://formatinternet.com"},
{"rel":"twittEr", "uri":"http//twitter.com/supercoco9"}
]}
*ningún gatico (ni ningún friki ansioso) ha sido dañado para hacer esta presentación