RESTful para todos

RESTful para todos

Cómo diseñar APIs RESTful sin morir en el intento.

Vivimos en un mundo orientado a servicios interconectados. Las protagonistas de esta evolución: las APIs RESTful. Si tu aplicación está enfocada a servicios y al mundo entero tenés que saber cómo encararlas. Mostraré las mejores prácticas para diseñar APIs restful, desde su concepción hasta su ejecución, testing y documentación. Modelado de Entidades y colecciones, errores, estándares y mucho más. Con esta información estarás en condiciones de diseñar la API RESTful de tu próxima Startup multimillonaria :)

Realizada en:

- NetConf.uy Octubre 2014 (http://netconf.uy/)
- PHPmvd Noviembre 2014 (http://phpmvd.uy)

1f135de4ac57d1eb89bab274175a4d66?s=128

Diego Sapriza

October 03, 2014
Tweet

Transcript

  1. RESTful 4 all Diego Sapriza diego@sapriza.net @AV4TAr

  2. Como diseñar una API RESTful sin morir en el intento.

  3. Hi!Diego Sapriza I’M @AV4TAr

  4. None
  5. PHP.meetup.uy DevOps.meetup.uy . .uy

  6. “El mundo evoluciona constantemente”

  7. Restful api versionamiento recursos status codes autenticación mensajes paginación documentación

    hypermedia (HATEOAS) verbos tools
  8. Quiénes hacen mayoritariamente Web dev?

  9. REpresentational State transfer técnica de arquitectura no es un estándar

  10. Acuerdo https://www.flickr.com/photos/124247024@N07/

  11. None
  12. Roy Fielding escalabilidad :(

  13. restricciones escalabilidad Client-Server Stateless Cache Uniform Interfaces Layered System Code

    on demand (opcional)
  14. Richardson Maturity Model http://bit.ly/api-rmm

  15. 0: The Swamp of POX RPC  SOBRE  HTTP  

  16. JSON XML html images

  17. 0: The Swamp of POX GET     http://srv.com/addin/auto-­‐harvest/end-­‐job/:id/ errors/:errors_messages

      http://srv.com/addin/auto-­‐harvest/start-­‐job/:id
  18. Richardson Maturity Model http://bit.ly/api-rmm

  19. Uniform Interfaces • Identificación recursos. • Manipulación de recursos a

    través de su representación. • Mensajes auto-descriptivos. • Hypermedia como motor del estado de la aplicación (HATEOAS).
  20. 1: RECURSOS tienen una URI mapean entidad/es sustantivos

  21. uri scheme:hierarchical part[?query][#fragment] telnet://192.168.1.1 urn:isbn:978-1-449-3150-9 mailto:diego@sapriza.net https://api.twilio.com/2010-­‐04-­‐01

  22. identificación /recurso/:id   /recurso/:id/:acción   /?r=recurso&id=:id   /?r=recurso&id=:id&a=:acción

  23. colecciones /recursos   /recursos/:id   /recursos/:id?pagina=:n&limite=100

  24. Richardson Maturity Model

  25. Uniform Interfaces • Identificación recursos. • Manipulación de recursos a

    través de su representación. • Mensajes auto-descriptivos. • Hypermedia como motor del estado de la aplicación (HATEOAS).
  26. Representación

  27. HTTP verbs Get Post Put Delete Patch Options Head Trace

    Connect http://bit.ly/http-­‐request-­‐methods
  28. crud http CREATE POST READ GET UPDATE PUT DELETE DELETE

  29. método seguro idempotente cachable GET HEAD POST PUT DELETE http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.2

  30. GET /personas Obtener  lista  de  personas POST /personas Agregar  una

     persona DELETE /personas/:id Eliminar  una  persona GET /personas/:id Obtener  una  persona PUT /personas/:id Actualizar  una  persona GET /personas/:id/contactos Obtener  los  contactos  de   una  persona POST /personas/:id/contactos Agregar  un  contacto  a  una   persona POST /personas/subirImagen Subir  una  imagen
  31. y ahora… ¿qué hacemos con estos msjs?

  32. Richardson Maturity Model

  33. Documentar…

  34. Uniform Interfaces • Identificación recursos. • Manipulación de recursos a

    través de su representación. • Mensajes auto-descriptivos. • Hypermedia como motor del estado de la aplicación (HATEOAS).
  35. auto-descriptivos ¿Cómo procesar el mensaje? ¿qué parser utilizar? ¿Caching?

  36. ahora… ¿cómo son los mensajes? HAL Collection JSON Siren

  37. HTTP/1.1 200 OK Content-Type: application/json { "status":"ok", "message":"Data retrieved OK!",

    "data" : [ { "id": 90, "modelId": 81, "path": "Somewhere over the rainbow.rvt" }, { "id": 91, "modelId": 13, "path": "Blue birds fly.rvt” }] } GET  http://server/addin/auto-­‐harvest/get-­‐jobs/ o_O
  38. HTTP/1.1 200 OK Content-Type: application/json { "status":"error", "message":"Page not found”,

    "data" : [] } o_O
  39. status codes 2xx - Success 3xx - Redirection 4xx -

    Client Error 5xx - Server Error
  40. Error messages api-problem HTTP/1.1 401 Unauthorized Content-Type: application/problem+json { "type":

    "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized", "authentication_uri": "/oauth" }
  41. Uniform Interfaces • Identificación recursos. • Manipulación de recursos a

    través de su representación. • Mensajes auto-descriptivos. • Hypermedia como motor del estado de la aplicación (HATEOAS).
  42. HATEOAS Clients make state transitions only through actions that are

    dynamically identified within hypermedia by the server. Except for simple fixed entry points to the application, a client does not assume that any particular action is available for any particular resources beyond those described in representations previously received from the server.
  43. clase.php public class Customer { public $Id; public $Name; }

  44. json { "id" : "1" "name" : "Diego" }

  45. HAL http://bit.ly/hal-spec { "id": "diego", "name": "Diego Sapriza”, "_links": {

    "self": { "href": "http://web.org/api/users/diego" }, "website": { "href": "http://web.org/api/locations/diego" } } }
  46. HAL { .. *snip* .. "_embedded": { "website": { "_links":

    { "self": { "href": “http://web.org/api/locations/diego" } }, "id": "diego", "url": "http://diego.uy" } } }
  47. HAL - colecciones { "_links": { "self" :{ "href": "http://web.org/api/user?page=3"

    }, "first":{ "href": "http://web.org/api/user" }, "prev" :{ "href": "http://web.org/api/user?page=2" }, "next" :{ "href": "http://web.org/api/user?page=4" }, "last" :{ "href": "http://web.org/api/user?page=133" } }, "count": 3, "total": 498, ... }
  48. https://api.github.com

  49. { "current_user_url": "https://api.github.com/user", "authorizations_url": "https://api.github.com/authorizations", "emails_url": "https://api.github.com/user/emails", "emojis_url": "https://api.github.com/emojis", "events_url":

    "https://api.github.com/events", "feeds_url": "https://api.github.com/feeds", "following_url": "https://api.github.com/user/following{/target}", "gists_url": "https://api.github.com/gists{/gist_id}", "hub_url": "https://api.github.com/hub", "issues_url": "https://api.github.com/issues", "keys_url": "https://api.github.com/user/keys", "notifications_url": "https://api.github.com/notifications", ... } https://api.github.com
  50. { "current_user_url": "https://api.github.com/user", "authorizations_url": "https://api.github.com/authorizations", "emails_url": "https://api.github.com/user/emails", "emojis_url": "https://api.github.com/emojis", "events_url":

    "https://api.github.com/events", "feeds_url": "https://api.github.com/feeds", "following_url": "https://api.github.com/user/following{/target}", "gists_url": "https://api.github.com/gists{/gist_id}", "hub_url": "https://api.github.com/hub", "issues_url": "https://api.github.com/issues", "keys_url": "https://api.github.com/user/keys", "notifications_url": "https://api.github.com/notifications", "organization_url": "https://api.github.com/orgs/{org}", "public_gists_url": "https://api.github.com/gists/public", "rate_limit_url": "https://api.github.com/rate_limit", "repository_url": "https://api.github.com/repos/{owner}/{repo}", "starred_url": "https://api.github.com/user/starred{/owner}{/repo}", "starred_gists_url": "https://api.github.com/gists/starred", "team_url": "https://api.github.com/teams", "user_url": "https://api.github.com/users/{user}", "user_organizations_url": "https://api.github.com/user/orgs", ... }
  51. Richardson Maturity Model http://bit.ly/api-rmm

  52. Sigamos links

  53. Restful api versionamiento recursos status codes autenticación mensajes paginación documentación

    hypermedia (HATEOAS) verbos tools
  54. Versiona tu API

  55. HTTP  GET   https://web.com/api/v1/users/diego

  56. HTTP  GET   https://web.com/api/users/diego   api-­‐version:  2

  57. HTTP  GET   https://web.com/api/users/diego   Accept:  application/vnd.myapi.v2+json

  58. HTTP  GET   https://web.com/api/users/diego por defecto última versión Headers para

    versiones anteriores
  59. autenticación

  60. crea tu propio método

  61. HTTP Basic Auth HTTP Digest OAuth2

  62. tools Postman Runscope jsonmate.com

  63. Restful api versionamiento recursos status codes autenticación mensajes paginación documentación

    hypermedia (HATEOAS) verbos tools
  64. None
  65. @AV4TAr http://AV4TAr.com https://speakerdeck.com/av4tar/restful-para-todos

  66. None
  67. We are hiring case.recruiterbox.com

  68. • http://www.troyhunt.com/2014/02/your-api-versioning-is- wrong-which-is.html • http://martinfowler.com/articles/ richardsonMaturityModel.html • http://www.vinaysahni.com/best-practices-for-a-pragmatic- restful-api •

    http://spf13.com/post/soap-vs-rest • https://leanpub.com/build-apis-you-wont-hate • https://speakerdeck.com/caseysoftware/on-the-edge-of- hypermedia-midwest-dot-io