¿por qué una api y cómo la diseño?

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

Jeremy Stanley

Ventana al mundo de nuestro negocio

Ventana de consulta

Federico Morando

Ventana bidireccional

Agus8n Rafael Reyes

Misma finalidad, distinta estructura

¿ Quién es el

responsable del diseño

de la API

¿ Quién es el

responsable del diseño

de la API

Funcionales + Técnicos

¿Cómo diseño la ventana?

API?

Graham

Chechi Peinado

Estructura base

http://base/nombre-api/version/recursos

http://apis.aytolalaguna.com/turismo/v1/monumentos


http://base/nombre-api/version/recursos?... q=… limit=… offset=…

PARÁMETROS


RECURSOS


RECURSOS

Modelado simple e intuitivo

Colecciones y elementos

northb

aywande

rer

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.

Métodos

1.  ¿Qué operaciones necesitamos realizar?

CREAR CONSULTAR BORRAR ACTUALIZAR



municipios /municipios /municipios/{id-‐municipio}



municipios /municipios /municipios/{id-‐municipio}

municipios

/listadoMunicipios /crearMunicipio /consultarMunicipio/{id-‐municipio} /actualizarMunicipio/{id-‐municipio} /borrarMunicipio/{id-‐municipio}



POST GET DELETE PUT / PATCH

Usamos los métodos HTTP


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

Simon Cunningham

2. ¿Cuál es el método por defecto?

/municipios

El método por defecto es “GET”

4 posibles opciones

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!!

Sustantivos vs Verbos

Steve Jurvetson

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

Plural!

Singular!

vs!

/municipios

/municipio

/hoteles

/hotel

/rutasTuristicas

/rutaTuristica

Se debe a que la respuesta de esa petición devuelve una colección

de elementos

Relaciones entre recursos

rutasTuristicas

/rutasTuristicas

/rutasTuristicas/{id_ruta}

rutasTuristicas monumentos recorren

/rutasTuristicas



/rutasTuristicas


/monumentos

/monumentos/{id_monumento}


/rutasTuristicas


/rutasTuristicas/{id_ruta}/monumentos

/monumentos

/monumentos/{id_monumento}

/monumentos/{id_monumento}/rutasTuristicas


Ejemplos:

/rutasTuristicas/HISTORICA/monumentos

/rutasTuristicas/RELIGIOSA/monumentos

/rutasTuristicas/MIEDO/monumentos

/monumentos/OBISPADO

/monumentos/CASA_LINARES

/monumentos/…

/recurso/{id_elemento}/recurso

/recurso/{id_elemento}/recurso

/recurso/{id_elemento}/recurso/{id_recurso}

Respuestas parciales

Webos fritos

• Nombre

• Apellidos

• Edad

• Dirección

• Cumpleaños

• Estado actual

• Formación

• Sexo

• Ciudad

• Intereses

• Deportes

• Grupos

• Amigos

• E-mail

• Citas

• …

Usuarios

• 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

Ignacio Conejo

Búsquedas

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:






/monumentos/…

Ejemplo de rutas turísticas:






/monumentos/…

/rutasTuristicas?q=OBISPADO in monumentos

Juan Carlos Mejía

Paginación de resultados

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

Formato de las respuestas

Jnj

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


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?


hTp://www.programmableweb.com/news/1-‐5-‐apis-‐say-‐bye-‐xml/2011/05/25


hTp://www.google.com/trends/explore?q=xml+api#q=xml%20api%2C%20json%20api&cmpt=q

Documentación

Gerardo Diego On8veros

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

Facebook Graph Api Explorer

Google Drive API Explorer

Ayu

nta

mie

nto

de

Za

rag

oza

3. API auto-documentada


/rutasTuristicas

/rutasTuristicas/HISTORICA


/rutasTuristicas/RELIGIOSA


/rutasTuristicas/MIEDO


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.

Rendimiento

Cloudave





Thomas Hawk

Los atributos

• 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)

Ge

stió

n d

e e

rro

res

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

Subdominios

APIS de Google

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?

Versionado


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


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

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)

Cloudave





¿por qué una api y cómo la diseño?

Technology