Upload
rita-diaz-adan
View
57
Download
1
Embed Size (px)
Citation preview
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
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
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.
1. ¿Qué operaciones necesitamos realizar?
CREAR CONSULTAR BORRAR ACTUALIZAR
municipios /municipios /municipios/{id-‐municipio}
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}
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}
1. ¿Qué operaciones necesitamos realizar?
CREAR CONSULTAR BORRAR ACTUALIZAR
POST GET DELETE PUT / PATCH
Usamos los métodos HTTP
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
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
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!!
1. Verbos no, sustantivos sí
Los nombres de los recursos deben ser sustantivos
Los verbos ya vienen dados por el método HTTP
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?
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
/municipios
/municipio
/hoteles
/hotel
/rutasTuristicas
/rutaTuristica
Se debe a que la respuesta de esa petición devuelve una colección
de elementos
rutasTuristicas monumentos recorren
/rutasTuristicas
/rutasTuristicas/{id_ruta}
/monumentos
/monumentos/{id_monumento}
rutasTuristicas monumentos recorren
/rutasTuristicas
/rutasTuristicas/{id_ruta}
/rutasTuristicas/{id_ruta}/monumentos
/monumentos
/monumentos/{id_monumento}
/monumentos/{id_monumento}/rutasTuristicas
rutasTuristicas monumentos recorren
Ejemplos:
/rutasTuristicas/HISTORICA/monumentos
/rutasTuristicas/RELIGIOSA/monumentos
/rutasTuristicas/MIEDO/monumentos
/monumentos/OBISPADO
/monumentos/CASA_LINARES
/monumentos/…
• Nombre
• Apellidos
• Edad
• Dirección
• Cumpleaños
• Estado actual
• Formación
• Sexo
• Ciudad
• Intereses
• Deportes
• Grupos
• Amigos
• Citas
• …
Usuarios
• Nombre
• Apellidos
• Edad
• Dirección
• Cumpleaños
• Estado actual
• Formación
• Sexo
• Ciudad
• Intereses
• Deportes
• Grupos
• Amigos
• Citas
• …
Usuarios
• Nombre
• Apellidos
• Edad
• Dirección
• Cumpleaños
• Estado actual
• Formación
• Sexo
• Ciudad
• Intereses
• Deportes
• Grupos
• Amigos
• Citas
• …
Usuarios
/usuarios?fields=nombre,apellidos,intereses
Uso del parámetro “fields”
Ejemplo API Facebook: /me?fields=id,first_name,last_name,gender
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.
Ejemplo de rutas turísticas:
/rutasTuristicas/HISTORICA/monumentos
/rutasTuristicas/RELIGIOSA/monumentos
/rutasTuristicas/MIEDO/monumentos
/monumentos/OBISPADO
/monumentos/CASA_LINARES
/monumentos/…
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
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
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
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
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.
2. ¿Qué formato escojo?
El preferido de nuestros consumidores El preferido de nuestros consumidores
El que mejor se adapte a nuestro negocio
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?
2. ¿Qué formato escojo?
hTp://www.programmableweb.com/news/1-‐5-‐apis-‐say-‐bye-‐xml/2011/05/25
2. ¿Qué formato escojo?
hTp://www.google.com/trends/explore?q=xml+api#q=xml%20api%2C%20json%20api&cmpt=q
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…
2. Portal del desarrollador
https://developers.google.com
https://developers.facebook.com
https://dev.twitter.com
rutasTuristicas monumentos recorren
/rutasTuristicas
/rutasTuristicas/HISTORICA
/rutasTuristicas/HISTORICA/monumentos
/rutasTuristicas/RELIGIOSA
/rutasTuristicas/RELIGIOSA/monumentos
/rutasTuristicas/MIEDO
/rutasTuristicas/MIEDO/monumentos
rutasTuristicas monumentos recorren
/rutasTuristicas
/rutasTuristicas/HISTORICA
/rutasTuristicas/HISTORICA/monumentos
/rutasTuristicas/RELIGIOSA
/rutasTuristicas/RELIGIOSA/monumentos
/rutasTuristicas/MIEDO
/rutasTuristicas/MIEDO/monumentos
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.
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
• Nombre
• Apellidos
• Edad
• Dirección
• Cumpleaños
• Estado actual
• Formación
• Sexo
• Ciudad
• Intereses
• Deportes
• Grupos
• Amigos
• 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)
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”}
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
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
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?
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?
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
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
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
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)