RESTful Para todos by Diego Sapriza
•
0 gostou•605 visualizações
Este documento proporciona una guía sobre cómo diseñar una API RESTful. Explica conceptos clave como recursos, verbos HTTP, códigos de estado, autenticación, representación de mensajes, paginación e hipermedia. También recomienda herramientas y buenas prácticas como la documentación, versionamiento y el uso de enlaces para navegar entre recursos.
Recomendados
Mais conteúdo relacionado
Semelhante a RESTful Para todos by Diego Sapriza
Semelhante a RESTful Para todos by Diego Sapriza (20)
Mais de .NET Conf UY
Mais de .NET Conf UY (18)
Último
Último (20)
RESTful Para todos by Diego Sapriza
- 1. RESTful 4 all Diego Sapriza diego@sapriza.net @AV4TAr
- 2. Como diseñar una API RESTful sin morir en el intento.
- 3. Hi!I’M Diego Sapriza @AV4TAr
- 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 no es un estándar
- 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
- 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
- 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?
- 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. clase.c# public class Customer! {! ! public int Id { get; set; }! ! public string Name { get; set; }! }!
- 45. json { ! "id" : "1"! "name" : "Diego"! }!
- 46. HAL http://bit.ly/hal-spec {! "id": "diego",! "name": "Diego Sapriza”,! ! "_links": {! "self": {! "href": "http://web.org/api/user/diego"! },! "website": {! "href": "http://web.org/api/locations/diego"! }! }! } !
- 47. HAL {! .. *snip* ..! "_embedded": {! "website": {! "_links": {! "self": {! "href": “http://web.org/api/locations/diego"! }! },! "id": "diego",! "url": "http://diego.uy"! }! }! }!
- 48. 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,! ...! }
- 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
- 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
- 67. • 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