Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

¿Por qué una API y cómo la diseño?

568 views

Published on

Las APIs nos permiten abrir una ventana al mundo que exponga nuestro negocio. Pueden usarse para lograr la
interoperabilidad de sistemas o para difundir datos pero si algo deben tener en común, es que deben estar correctamente diseñadas y atender a las necesidades para las que se idearon.

Published in: Technology
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download Full EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download Full doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book THIS can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer THIS is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story THIS Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money THIS the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths THIS Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

¿Por qué una API y cómo la diseño?

  1. 1. Cloudave   JORNADA TÉCNICA #turisTICa organizada por: ¿Por qué una API y cómo la diseño? Rita Díaz Adán @rdiaada 20 de Octubre de 2014
  2. 2. Jeremy  Stanley   Ventana al mundo de nuestro negocio
  3. 3. Ventana de consulta
  4. 4. Federico  Morando   Ventana bidireccional
  5. 5. Agus8n  Rafael  Reyes   Misma finalidad, distinta estructura
  6. 6. ¿ Quién es el responsable del diseño de la API
  7. 7. ¿ Quién es el responsable del diseño de la API Funcionales + Técnicos
  8. 8. ¿Cómo diseño la ventana? API? Graham  
  9. 9. Chechi  Peinado   Estructura base
  10. 10. http://base/nombre-api/version/recursos
  11. 11. http://base/nombre-api/version/recursos
  12. 12. http://apis.aytolalaguna.com/turismo/v1/monumentos http://base/nombre-api/version/recursos
  13. 13. http://base/nombre-api/version/recursos?... q=… limit=… offset=… PARÁMETROS
  14. 14. http://base/nombre-api/version/recursos RECURSOS
  15. 15. http://base/nombre-api/version/recursos RECURSOS Modelado simple e intuitivo
  16. 16. Colecciones y elementos northbaywanderer  
  17. 17. 1. ¿Qué necesitamos modelar? COLECCIONES DE RECURSOS https://.../municipios ELEMENTOS https://.../municipios/santa-cruz https://.../municipios/la-laguna https://.../municipios/puerto-de-la-cruz Para cada recurso sólo necesitamos dos URL
  18. 18. 2. ¿Qué información debe devolver cada petición? COLECCIONES DE RECURSOS: https://.../municipios Un resumen de cada elemento que forma parte de la colección. La información más frecuente es: código, nombre, enlaces. ELEMENTOS: https://.../municipios/la-laguna Toda la información referente al elemento de la petición.
  19. 19. Métodos
  20. 20. 1.  ¿Qué operaciones necesitamos realizar? CREAR  CONSULTAR   BORRAR  ACTUALIZAR  
  21. 21. 1.  ¿Qué operaciones necesitamos realizar? CREAR  CONSULTAR   BORRAR  ACTUALIZAR   municipios   /municipios   /municipios/{id-­‐municipio}  
  22. 22. 1.  ¿Qué operaciones necesitamos realizar? CREAR  CONSULTAR   BORRAR  ACTUALIZAR   municipios   /municipios   /municipios/{id-­‐municipio}   municipios   /listadoMunicipios   /crearMunicipio   /consultarMunicipio/{id-­‐municipio}   /actualizarMunicipio/{id-­‐municipio}   /borrarMunicipio/{id-­‐municipio}  
  23. 23. 1.  ¿Qué operaciones necesitamos realizar? CREAR  CONSULTAR   BORRAR  ACTUALIZAR   municipios   /municipios   /municipios/{id-­‐municipio}   municipios   /listadoMunicipios   /crearMunicipio   /consultarMunicipio/{id-­‐municipio}   /actualizarMunicipio/{id-­‐municipio}   /borrarMunicipio/{id-­‐municipio}  
  24. 24. 1.  ¿Qué operaciones necesitamos realizar? CREAR  CONSULTAR   BORRAR  ACTUALIZAR   POST  GET   DELETE  PUT  /  PATCH   Usamos los métodos HTTP
  25. 25. 1.  ¿Qué operaciones necesitamos realizar? RECURSO GET consultar POST crear PUT / PATCH actualizar DELETE borrar /municipios Obtiene la lista de municipios Crea un nuevo municipio Actualiza múltiples municipios Borra todos los municipios /municipios/la-laguna Obtiene los datos de La Laguna ERROR Si existe La Laguna: la actualiza. Si no existe La Laguna: ERROR Borra el municipio La Laguna
  26. 26. Simon  Cunningham  
  27. 27. 2. ¿Cuál es el método por defecto? /municipios El método por defecto es “GET” 4 posibles opciones
  28. 28. 3. Buscadores y el método GET /municipios 4 posibles opciones CREAR /municipios?method=post CONSULTAR /municipios ACTUALIZAR /municipios?method=put&name=Laguna ELIMINAR /municipios?method=delete
  29. 29. 3. Buscadores y el método GET /municipios 4 posibles opciones CREAR /municipios?method=post CONSULTAR /municipios ACTUALIZAR /municipios?method=put&name=Laguna ELIMINAR /municipios?method=delete ¡¡Las arañas de los buscadores (ej.Googlebot) podrían modificar nuestro contenido!!
  30. 30. Sustantivos vs Verbos  Steve  Jurvetson  
  31. 31. 1. Verbos no, sustantivos sí Los nombres de los recursos deben ser sustantivos Los verbos ya vienen dados por el método HTTP
  32. 32. 1. Verbos no, sustantivos sí Los nombres de los recursos deben ser sustantivos Los verbos ya vienen dados por el método HTTP ¿Existe alguna excepción a esta regla?
  33. 33. 2. Verbos sólo cuando…. … la respuesta no es un recurso sino el resultado de una acción •  Suelen ser acciones del tipo: traducir, convertir o calcular. •  Se debe dejar bien documentado en la documentación de la API
  34. 34. Plural! Singular! vs!
  35. 35. /municipios /municipio /hoteles /hotel /rutasTuristicas /rutaTuristica Se debe a que la respuesta de esa petición devuelve una colección de elementos
  36. 36. Relaciones entre recursos
  37. 37. rutasTuristicas /rutasTuristicas /rutasTuristicas/{id_ruta}
  38. 38. rutasTuristicas monumentos recorren /rutasTuristicas /rutasTuristicas/{id_ruta}
  39. 39. rutasTuristicas monumentos recorren /rutasTuristicas /rutasTuristicas/{id_ruta} /monumentos /monumentos/{id_monumento}
  40. 40. rutasTuristicas monumentos recorren /rutasTuristicas /rutasTuristicas/{id_ruta} /rutasTuristicas/{id_ruta}/monumentos /monumentos /monumentos/{id_monumento} /monumentos/{id_monumento}/rutasTuristicas
  41. 41. rutasTuristicas monumentos recorren Ejemplos: /rutasTuristicas/HISTORICA/monumentos   /rutasTuristicas/RELIGIOSA/monumentos   /rutasTuristicas/MIEDO/monumentos     /monumentos/OBISPADO   /monumentos/CASA_LINARES   /monumentos/…  
  42. 42. /recurso/{id_elemento}/recurso  
  43. 43. /recurso/{id_elemento}/recurso     /recurso/{id_elemento}/recurso/{id_recurso}  
  44. 44. Respuestas parciales Webos  fritos  
  45. 45. • Nombre • Apellidos • Edad • Dirección • Cumpleaños • Estado actual • Formación • Sexo • Ciudad • Intereses • Deportes • Grupos • Amigos • E-mail • Citas • … Usuarios
  46. 46. • Nombre • Apellidos • Edad • Dirección • Cumpleaños • Estado actual • Formación • Sexo • Ciudad • Intereses • Deportes • Grupos • Amigos • E-mail • Citas • … Usuarios
  47. 47. • Nombre • Apellidos • Edad • Dirección • Cumpleaños • Estado actual • Formación • Sexo • Ciudad • Intereses • Deportes • Grupos • Amigos • E-mail • Citas • … Usuarios /usuarios?fields=nombre,apellidos,intereses   Uso del parámetro “fields” Ejemplo API Facebook: /me?fields=id,first_name,last_name,gender  
  48. 48. Ignacio  Conejo   Búsquedas
  49. 49. 1. ¿Qué búsquedas necesitamos? 1. BÚSQUEDAS EN COLECCIONES DE RECURSOS /municipios?q=laguna   /municipios?q=name  ilike  laguna  and  isla  eq  tenerife       2. BÚSQUEDAS GLOBALES /search?q=laguna   DOCUMENTACIÓN Obtenemos todos los recursos que existen en nuestra API que cumplen la condición.
  50. 50. Ejemplo de rutas turísticas: /rutasTuristicas/HISTORICA/monumentos   /rutasTuristicas/RELIGIOSA/monumentos   /rutasTuristicas/MIEDO/monumentos     /monumentos/OBISPADO   /monumentos/CASA_LINARES   /monumentos/…  
  51. 51. Ejemplo de rutas turísticas: /rutasTuristicas/HISTORICA/monumentos   /rutasTuristicas/RELIGIOSA/monumentos   /rutasTuristicas/MIEDO/monumentos     /monumentos/OBISPADO   /monumentos/CASA_LINARES   /monumentos/…   /rutasTuristicas?q=OBISPADO  in  monumentos  
  52. 52. Juan  Carlos  Mejía   Paginación de resultados
  53. 53. 1. ¿Qué hay que tener en cuenta? •  Uso del parámetro limit •  Uso del parámetro offset •  Establecer valores por defecto para ambos parámetros   Ejemplos:   /municipios?limit=2&offset=5           /municipios?limit=10&offset=0        
  54. 54. Formato de las respuestas Jnj  
  55. 55. 1. ¿Cómo especificamos el formato? OPCIÓN 1. EN LA CABECERA DE LA PETICIÓN Accept:application/json   OPCIÓN 2. COMO SI SE TRATARA DE UNA EXTENSIÓN /municipios.json   OPCIÓN 3. COMO PARÁMETRO /municipios?type=json /municipios?alt=json /municipios?format=json
  56. 56. 1. ¿Cómo especificamos el formato? OPCIÓN 1. EN LA CABECERA DE LA PETICIÓN Accept:application/json   OPCIÓN 2. COMO SI SE TRATARA DE UNA EXTENSIÓN /municipios.json   OPCIÓN 3. COMO PARÁMETRO /municipios?type=json /municipios?alt=json /municipios?format=json
  57. 57. 1. ¿Cómo especificamos el formato? •  El primer método es compatible con cualquiera de los otros dos •  Si se permiten ambos métodos y se indicase información contradictoria, el segundo prevalecería. •  Debe existir un formato por defecto.  
  58. 58. 2. ¿Qué formato escojo? El preferido de nuestros consumidoresEl preferido de nuestros consumidores El que mejor se adapte a nuestro negocio
  59. 59. 2. ¿Qué formato escojo? El preferido de nuestros consumidores El que mejor se adapte a nuestro negocio ¿Y si desconozco el formato preferido? ¿Y si cualquiera se adapta bien?
  60. 60. 2. ¿Qué formato escojo? hTp://www.programmableweb.com/news/1-­‐5-­‐apis-­‐say-­‐bye-­‐xml/2011/05/25    
  61. 61. 2. ¿Qué formato escojo? hTp://www.google.com/trends/explore?q=xml+api#q=xml%20api%2C%20json%20api&cmpt=q    
  62. 62. Documentación Gerardo  Diego  On8veros  
  63. 63. 1. ¿Es necesario documentar la API? •  La documentación debe ser tan buena como la propia API. •  La documentación debe ser fácil de localizar. •  La documentación debe estar accesible públicamente. •  La documentación debe incluir los cambios de cada versión. •  La documentación debe incluir ejemplos.   Sí, debemos documentarla y además…
  64. 64. 2. Portal del desarrollador https://developers.google.com https://developers.facebook.com https://dev.twitter.com
  65. 65. Facebook Graph Api Explorer
  66. 66. Google Drive API Explorer
  67. 67. AyuntamientodeZaragoza
  68. 68. 3. API auto-documentada
  69. 69. rutasTuristicas monumentos recorren /rutasTuristicas    /rutasTuristicas/HISTORICA        /rutasTuristicas/HISTORICA/monumentos    /rutasTuristicas/RELIGIOSA        /rutasTuristicas/RELIGIOSA/monumentos    /rutasTuristicas/MIEDO        /rutasTuristicas/MIEDO/monumentos  
  70. 70. rutasTuristicas monumentos recorren /rutasTuristicas    /rutasTuristicas/HISTORICA        /rutasTuristicas/HISTORICA/monumentos    /rutasTuristicas/RELIGIOSA        /rutasTuristicas/RELIGIOSA/monumentos    /rutasTuristicas/MIEDO        /rutasTuristicas/MIEDO/monumentos  
  71. 71. 2. API auto-documentada •  Cada respuesta debe contener los enlaces a: •  La propia petición (self) •  Padre (parent) •  Hijos (childs) Para más información consultar las referencias de HATEOAS.
  72. 72. Rendimiento
  73. 73. Cloudave   JORNADA TÉCNICA #turisTICa organizada por: ¿Por qué una API y cómo la diseño? Rita Díaz Adán @rdiaada 20 de Octubre de 2014
  74. 74. Thomas  Hawk  
  75. 75. Los atributos
  76. 76. • Nombre • Apellidos • Edad • Dirección • Cumpleaños • Estado actual • Formación • Sexo • Ciudad • Intereses • Deportes • Grupos • Amigos • E-mail • Citas • … Usuarios OPCIÓN 1.  estado_acual     OPCIÓN 2.  EstadoActual     OPCIÓN 3.  estadoActual   En general seguiremos las convenciones del nombrado de atributos en JavaScript (Útil en el uso de JSON.parse)
  77. 77. Gestióndeerrores
  78. 78. 1. ¿Qué código HTTP devolvemos? OPCIÓN 1. SIEMPRE VA BIEN HTTP Status code: 200 {“type”  :  “OauthException”,     “message”:”(#803)  Some  of  the  aliases  you  requested  do  not  exist:  foo.bar”}     OPCIÓN 2. UN CÓDIGO HTTP PARA CADA ERROR HTTP Status code: 401 {“code”  :  401,     “message”:”Authentication  required”}    
  79. 79. 1. ¿Qué código HTTP devolvemos? •  Cuando existe un error debemos devolver un código HTTP de error. •  Deberíamos soportar al menos los siguientes códigos: •  200: OK - Todo fue bien. •  400: Bad request – La petición no es correcta. •  500: Internal server error – Se ha producido un error dentro de la lógica de la aplicación. •  Otros códigos que podemos soportar: •  201: Created •  304: Not modified •  404: Nor found   •  401: Unauthorized •  403: Forbidden
  80. 80. 2. Mensajes de error •  Deben existir mensajes de error que complementen el código. •  Deben ser lo más extensos posibles. •  Deben estar escritos en lenguaje claro. •  Se pueden añadir links para información adicional.   HTTP  Status  Code:  401.   {“status”  :  401,     “message”:”Authentication  required”,   “code”:  200003,   “more  info”:  “http://www.twilio.com/docs/errors/200003”}     Ejemplo de Twilio
  81. 81. Subdominios
  82. 82. APIS de Google
  83. 83. OPCIÓN 2. MÚLTIPLES APIS, UN SUBDOMINIO https://www.googleapis.com/drive/v… https://www.googleapis.com/books/v… https://www.googleapis.com/prediction/v… OPCIÓN 1. UNA API, UN SUBDOMINIO https://drive.googleapis.com/v.. https://books.googleapis.com/v… https://prediction.googleapis.com/v… 1. ¿Cómo las organizamos?
  84. 84. OPCIÓN 2. MÚLTIPLES APIS, UN SUBDOMINIO https://www.googleapis.com/drive/v… https://www.googleapis.com/books/v… https://www.googleapis.com/prediction/v… OPCIÓN 1. UNA API, UN SUBDOMINIO https://drive.googleapis.com/v.. https://books.googleapis.com/v… https://prediction.googleapis.com/v… Limpio, sencillo, intuitivo 1. ¿Cómo las organizamos?
  85. 85. Versionado
  86. 86. http://base/nombre-api/version/recursos https://www.googleapis.com/prediction/v1.2 https://www.googleapis.com/drive/v2 https://api.twilio.com/2010-04-01 https://api.twitter.com/1.1 https://graph.facebook.com/…?v=1.0 1. Formato de las versiones
  87. 87. http://base/nombre-api/version/recursos https://www.googleapis.com/prediction/v1.2 https://www.googleapis.com/drive/v2 https://api.twilio.com/2010-04-01 https://api.twitter.com/1.1 https://graph.facebook.com/…?v=1.0 https://graph.facebook.com/v2.1 1. Formato de las versiones
  88. 88. 2. Otras consideraciones Siguiendo el siguiente formato vX Siempre obligatoria Siempre parte de la URL Mantener al menos dos versiones Uso de la palabra reservada “latest” *   v1   http://apis.turistica.es/mi-­‐api/latest   http://apis.turistica.es/mi-­‐api/v4  
  89. 89. Referencias
  90. 90. Referencias •  Web API Design – Crafting interfaces that Developers Love (Brian Mulloy - Apigee). •  1 in 5 APIs say “Bye XML” (Adam DuVander – ProgrammableWeb). •  HATEOAS 101: Introduction to a Rest Api Style (Helen Whelan). •  API Design: Honing in on HATEOAS (Brian Mulloy) •  Haters gonna HATEOAS (Steve Klabnik) •  Link Relations (Matt Nottingham, Julian Reschke, Jan Algermissen) •  Best practices for designing a pragmatic RESTful API (Vinay Sahni)
  91. 91. Cloudave   JORNADA TÉCNICA #turisTICa organizada por: ¿Por qué una API y cómo la diseño? Rita Díaz Adán @rdiaada 20 de Octubre de 2014

×