¿Cómo escalar mi API REST?

Seguimos insistiendo con las API’s. Esta semana me gustaría reforzar el post de Chiyana para mantener tu API RESTful. Es fundamental mantener y prever un escalado de tu API, aún más si aplicas un modelo de API Economy.

Es fundamental facilitar el consumo de tus API’s a tus clientes o partners. Cómo ya hablamos sobre cómo hacer que tus APIs sean RESTful, hoy hablaremos sobre 3 puntos que harán escalar tu API:

• Reporte de errores
• Respuestas parciales
• Versionado

Reporte de errores

No podrás controlar que aparezcan errores y excepciones, sobretodo si delegas el desarrollo de aplicaciones, mediante tú API, a terceros. Es por ello que es importante reportar los errores, de forma que ayude al desarrollador a solucionarlos de forma eficaz.

Como se comentó en el post “mantener mi API RESTful”, usar el código HTTP adecuado es de obligación para entender el tipo de error que se está produciendo. Esta codificación es heredada de webs estáticas y en algún caso puede ser un lenguaje demasiado básico para llegar a explicar y/o comprender el error que se está produciendo.

En el caso de una API REST, cada URL es un endpoint que ejecutara una acción concreta, produciendo una cadena de servicios en el servidor. Veamos cómo podemos mejorar esta comunicación. El objetivo es aportar al desarrollador información valiosa, que le permita resolver los problemas de forma sencilla y estructurada, facilitando su tarea.

Códigos de estado HTTP vs Códigos de error REST

Los códigos de estado HTTP no son suficientes para distinguir entre un error que ocurrió en el servidor o un error que ocurrió debido a una mala llamada al endpoint de la API.

Pongamos como ejemplo una URL que resuelve a un endpoint de tu API REST, el estado HTTP debería ser 200 OK. Pero si en el momento de ejecutar la función del endpoint falta por ejemplo algún parámetro required, técnicamente eso debería ser un estado HTTP: 400 Bad Request, 500 Internal Server Error, 404 Not Found o un 422 Unprocessable Entity. Entonces, ¿Que devuelvo? ¿200, 400, 500, 404, 422..?

Facebook por ejemplo, ha decidido devolver 200 si el endpoint existe. Cualquier error se devuelve de forma estructurada en la respuesta de la petición. A esto se le conoce como “envelope”.

Un “evelope” es una respuesta que contiene el objeto JSON principal dentro de una clave JSON. De este modo podemos añadir información adicional a las respuestas. Veamos algún ejemplo.

Respuesta JSON simple:

Respuesta JSON “envelope”:

Respuesta JSON “envelope” con error:

Como ves en el último ejemplo, si hay un error, el desarrollador puede acceder de forma fácil y con una estructura genérica a la información.

Idealmente, como hemos puesto en el ejemplo, se debería generar códigos de errores personalizados, que el desarrollador pueda encontrar en el portal de soporte API. Esta estructura de error debería tener un esquema diseñado de forma escalable, para mantener la misma estructura en todo sistema y facilitar al desarrollador el análisis de errores.

Además puedes trazar los errores con los consumidores de tu API. En el ejemplo, podréis ver la variable “fbtrace_id”, esta es la variable de trazabilidad de errores de Facebook. Esta variable contiene el identificador concreto del error del usuario, con lo que se puede hacer trazabilidad del mismo integrando tu API a un sistema de reporte de errores como Sentry.

También sería interesante incluir un enlace al manual de la API, con más información sobre el error / excepción, con la variable _links, tal como explica Chiyana en “mantener mi API RESTful” con HATEOAS.  Por ejemplo utilzando help:

Respuestas parciales

El rendimiento, es muy importante. Si alguno de tus endpoints API manejan mucha información, esto afecta directamente al rendimiento y ancho de banda de tus servicios y de los consumidores finales.

Las respuestas parciales permiten al desarrollador especificar los campos que requiera en cada momento. A diferencia de devolver automáticamente todas las variables en cada respuesta ocupando posiblemente un ancho de banda innecesario y afectando al rendimiento del usuario final. Por esto mismo, GraphQL es, actualmente, tan nombrado entre los desarrolladores y desarrolladores de APIs.

Para poder aplicar las respuestas parciales de forma genérica y no crear un endpoint para cada tipo de respuesta parcial, deberás añadir un nuevo parámetro de entrada donde se especificarán las variables que se requieran por cada respuesta. Veamos un ejemplo:

De este modo los desarrolladores pueden obtener exactamente las variables, en el ejemplo se solicitan únicamente las variables age y location. De este modo se reduce el ancho de banda y rendimiento, sin alterar el número de endpoint por cada casuística.

Versionado

El versionado es la clave del éxito a largo plazo de tu API. Al igual que cuando giras la llave de tu casa para salir por la puerta. Los desarrolladores esperan lo mismo de la API, que el funcionamiento no se vea alterado por nuevas implementaciones o innovaciones.

“The doors in the story illustrate what happens when discoverability fails.”
          The design of Everyday Things. Don Norman.

Siempre que no alteres el orden normal de las cosas, puedes añadir mejoras en el sistema sin avisar, pero manteniendo la misma estructura de lo que había anteriormente. Por ejemplo si se añade una nueva variable, el desarrollador puede verla o no. Pero no importa, ya que todavía podrá seguir utilizando el mismo sistema sin alterar el funcionamiento.

El problema se produce en el momento en que se implementa algún cambio en el formato de respuesta, los parámetros de entrada o los métodos de consulta.

Tu sistema API deberá evolucionar para estar alineado a tu modelo de negocio, además de evolucionar tecnológicamente. Las necesidades de los clientes evolucionan, al igual que los mercados cambian, así que deberás versionar tu API REST.

Para identificar la versión, deberías estructurar las versiónes en 2 apartados:

        major_version.minor_version

major_version: Se trata de una versión disruptiva. Puede llegar a alterar el funcionamiento de los desarrollos que estén en producción consumiendo la API.

minor_version: Cambios mínimos como mejoras no significativas o parches de seguridad. Estos no deben alterar el formato de respuesta, los parámetros de entrada o los métodos de consulta.

Deprecation y Releases

Cuando aumentes la major_version, deberás avisar a todos los desarrolladores. Además, deberás establecer un período durante el cual tendrás que permitir la existencia de ambas versiones API. Es un tiempo prudencial que permita a los desarrolladores modificar los desarrollos para pasar las funciones “deprecated” o las nuevas “releases”.

Para mantener esta convivencia, podrás estructurarla de 2 formas:

1. Endpoint API

Especifica la versión en el endpoint. Por ejemplo:

2. Encabezado HTTP personalizado con MIME

Mediante el tipo de contenido MIME, el cliente API envía un subtipo MIME personalizado junto con el tipo de aplicación. El resultado sería:

Conclusión

Sin ninguna duda deberás escalar tu API. Escalar no se trata únicamente de autoescalar con un API Gateway, sino que debes mantener tu API REST eficiente para tus consumidores.

Escala tu API REST ayudando a los desarrolladores con los problemas que puedan encontrarse mediante los reportes de errores. Ofrecerles un mejor rendimiento con respuestas parciales. Además de mantener un versionado para el manejo de nuevas implementaciones API REST.

Recuerda, si frustras a tus desarrolladores, dejarán de consumir tu servicio. Crea una buena documentación, tutoriales y sobretodo un canal de soporte para brindar a los desarrolladores toda la ayuda que necesitan.

Debes ayudar a los desarrolladores a usar tu API. Los clientes de tu API son desarrolladores.

¿La API REST de tu organización es escalable? ¿Utilizas algún sistema de reporte de errores? ¿Te preocupa el rendimiento? ¿Aplicas versionado? Si tienes dudas sobre cómo escalar tu API REST, escríbenos y te ayudamos a desarrollar tus proyectos.

Imagen de Alain Audet en Pixabay

Referencias:

• How To Scale Your REST API
• RESTful API Design Tips from Experience