¿Por qué una API y cómo la diseño?
•
2 recomendaciones•696 vistas
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.
Recomendados
Más contenido relacionado
Destacado
Destacado (12)
Similar a ¿Por qué una API y cómo la diseño?
Similar a ¿Por qué una API y cómo la diseño? (20)
Último
Último (20)
¿Por qué una API y cómo la diseño?
- 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. Jeremy Stanley Ventana al mundo de nuestro negocio
- 4. Federico Morando Ventana bidireccional
- 5. Agus8n Rafael Reyes Misma finalidad, distinta estructura
- 6. ¿ Quién es el responsable del diseño de la API
- 7. ¿ Quién es el responsable del diseño de la API Funcionales + Técnicos
- 9. Chechi Peinado Estructura base
- 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. 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. Métodos
- 20. 1. ¿Qué operaciones necesitamos realizar? CREAR CONSULTAR BORRAR ACTUALIZAR
- 21. 1. ¿Qué operaciones necesitamos realizar? CREAR CONSULTAR BORRAR ACTUALIZAR municipios /municipios /municipios/{id-‐municipio}
- 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. 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. 1. ¿Qué operaciones necesitamos realizar? CREAR CONSULTAR BORRAR ACTUALIZAR POST GET DELETE PUT / PATCH Usamos los métodos HTTP
- 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. Simon Cunningham
- 27. 2. ¿Cuál es el método por defecto? /municipios El método por defecto es “GET” 4 posibles opciones
- 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. 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. Sustantivos vs Verbos Steve Jurvetson
- 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. 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. 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
- 35. /municipios /municipio /hoteles /hotel /rutasTuristicas /rutaTuristica Se debe a que la respuesta de esa petición devuelve una colección de elementos
- 41. rutasTuristicas monumentos recorren Ejemplos: /rutasTuristicas/HISTORICA/monumentos /rutasTuristicas/RELIGIOSA/monumentos /rutasTuristicas/MIEDO/monumentos /monumentos/OBISPADO /monumentos/CASA_LINARES /monumentos/…
- 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
- 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. Ejemplo de rutas turísticas: /rutasTuristicas/HISTORICA/monumentos /rutasTuristicas/RELIGIOSA/monumentos /rutasTuristicas/MIEDO/monumentos /monumentos/OBISPADO /monumentos/CASA_LINARES /monumentos/…
- 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. Juan Carlos Mejía Paginación de resultados
- 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. Formato de las respuestas Jnj
- 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. 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. 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. 2. ¿Qué formato escojo? El preferido de nuestros consumidoresEl preferido de nuestros consumidores El que mejor se adapte a nuestro negocio
- 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. 2. ¿Qué formato escojo? hTp://www.programmableweb.com/news/1-‐5-‐apis-‐say-‐bye-‐xml/2011/05/25
- 61. 2. ¿Qué formato escojo? hTp://www.google.com/trends/explore?q=xml+api#q=xml%20api%2C%20json%20api&cmpt=q
- 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. 2. Portal del desarrollador https://developers.google.com https://developers.facebook.com https://dev.twitter.com
- 65. Facebook Graph Api Explorer
- 69. rutasTuristicas monumentos recorren /rutasTuristicas /rutasTuristicas/HISTORICA /rutasTuristicas/HISTORICA/monumentos /rutasTuristicas/RELIGIOSA /rutasTuristicas/RELIGIOSA/monumentos /rutasTuristicas/MIEDO /rutasTuristicas/MIEDO/monumentos
- 70. rutasTuristicas monumentos recorren /rutasTuristicas /rutasTuristicas/HISTORICA /rutasTuristicas/HISTORICA/monumentos /rutasTuristicas/RELIGIOSA /rutasTuristicas/RELIGIOSA/monumentos /rutasTuristicas/MIEDO /rutasTuristicas/MIEDO/monumentos
- 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. Rendimiento
- 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. Thomas Hawk
- 75. Los atributos
- 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. Gestióndeerrores
- 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. 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. 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. Subdominios
- 82. APIS de Google
- 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. 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. Versionado
- 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. Referencias
- 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. 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