Consejos a la hora de crear un API REST

¡Hola! ¿Qué tal estáis? Espero que bien 😁. Para mí esta semana ha sido infernal, me he tenido que pelear con un servicio antiguo basado en API REST y he visto como se han pasado por el FORRO todas las buenas prácticas 😅. No hay mal por bien que no venga así que me he decidido a escribir un tutorial con las que considero que son para Mí unas buenas prácticas para el correcto desarrollo de una API.

1.- Misma estructura para todas las respuestas

Algo que puede volver locos a los front que les toque trabajar con nuestra API y a nosotros mismos es no tener una misma estructura para todas las respuestas. Un ejemplo de una estructura que podría valernos para todas las respuestas podría ser este:

{
    "status": true,
    "msg": "ok",
    "data": []
}

Pues la idea sería utilizar estás mismas tres claves para todas las respuestas y ya solo modificar sus valores.

Ejemplos de distintas respuestas que me he encontrado en una misma API 😅:

api/posts: {"status": true, "msg": "ok"}
api/posts/1: {"status": "success", "message": "ok"}
api/comments: {"error": true, "message": "Error"}

Anarquía total 😂.

Para resolver esto puedes crear una clase Response que reciba si todo ha ido bien o no, el mensaje a enviar, los posibles datos que queramos enviar y el código de estado. De esta forma podremos controlar el formato de la respuesta y devolver siempre la misma estructura.

Os dejo un ejemplo en Python:

import json


class Response:

    def __init__(self, status=True, data=[], msg='ok', code=200):
        self.status = status
        self.msg = msg
        self.data = data
        self.code = code

    def send():
        return json.dumps(
            [
                'status': self.status,
                'msg': self.msg,
                'data': self.data,
                'code': self.code
            ]
        )

2.- Usar una herramienta para testar nuestra API

Una de las herramientas que más me han facilitado el trabajo a la hora de trabajar con APIs es Postman (no me pagan eh). Con esta herramienta puedes crear colecciones para guardar los endpoints que vas creando, automatizar el guardado de tokens para no tener que actualizarlos cada vez que caduquen o lo refresques. También tiene entornos (por ejemplo para trabajar con la url de prod o local). Vamos que es una maravilla, además puedes compartirlo con tus compis ya sea exportando tu colección o registrándote en su plataforma.

3.- Usar un estándar

Este paso está relacionado con el punto 1. Hay mil estándares en internet para dar formato a tus respuestas. Yo en mis proyectos estoy usando este, pero podéis usar el que más os guste: https://github.com/omniti-labs/jsend

4.- Documentación

Aquí me refiero tanto en el código como en un documento aparte. A ver no es documentar cada línea, pero si describe brevemente que hace cada función o método, que parámetros recibe y que debe retornar.

Una de las cosas que más he echado de menos a la hora de heredar un proyecto es no tener una página de documentación de la API. Te vuelves loco buscando los parámetros que tienes que enviar y no tienes una descripción básica de lo que hace el endpoint.

Hoy en día es más fácil que nunca gracias a herramientas como swagger (tampoco me pagan) que en casos como en node.js tienes la opción instalar la dependencia en tu proyecto, realizar unos pasos para configurarlo y ya podrás acceder a la doc desde el navegador en la que solo tendrás que editar un archivo yaml para añadir tus endpoints, una descripción, el método, parámetros, respuestas, etc.

5.- Test unitarios

Este punto se explica solo, una app sin test unitarios es una bomba de relojería en potencia. Mi consejo, cada vez que termines un endpoint, crea su batería de tests, ya que si te lo dejas para el final te va a dar pereza hacerlos o no vas a recordar todos los posibles casos de error que si se te ocurren cuando estás trabajando con ese endpoint al momento.

6.- Logging de errores

¿A quién no le ha llegado un usuario diciéndote que le está fallando una parte de un servicio, pero eres incapaz de reproducir un error porque ni él sabe que pasos siguió? A mí mil veces. Para esto lo mejor es ir capturando todos los errores y guardar toda la información relevante como la hora, los parámetros recibidos, el endpoint al que ataca... De esta forma iremos puliendo nuestra API para que sea lo más estable posible.

En este caso, existen librerías que podemos integrar en nuestros proyectos para el logging de información, errores, alertas, etc. Este tipo de librerías nos permiten registrar información y nosotros podemos decidir que nivel tienen, si es informativo, debug, warnings, errores y podemos guardarlos tanto en archivos de logs como mostrarlos en una terminal. También nos permiten elegir el nivel de información que queremos guardar. Por ejemplo si solo queremos guardar en un log errores, o errores y alertas.

7.- Controlar que errores le envías al usuario

Vale, esto me lo he encontrado mil veces, capturar una excepción y enviársela tal cual al usuario. Haciéndolo así podemos enviar información comprometida al usuario como datos de nuestra bbdd, posibles vulnerabilidades, etc. Si no somos capaces de identificar el error porque no lo tenemos controlado lo mejor es enviar un error genérico y hacer logging del error (punto 6) para solucionarlo más adelante.

8.- Utilizar los métodos de petición correctos

Aquí es donde más horrorizado he acabado. Lo último fue ver un método get que recibía parámetros por post 🙀. Ni siquiera sabía que era eso posible. Cuando utilizas un framework es más difícil que pase esto, pero si estáis trabajando en un proyecto con código puro os lo podéis encontrar. Si tenéis dudas sobre que métodos utilizar en cada caso, podéis mirar este resumen.

9.- Devolver el código de estado correcto

No hay nada peor que devolver un status 200 y luego ver una retahíla de errores en la respuesta o peor aún, que no devuelva nada y toque llenar de prints el código hasta dar con el error (Recordad, logging de errores). No hace falta conocer ni usarlos todos en tu proyecto, pero si conocer los básicos y dar un código de estado en relación con la respuesta que le quieras dar al usuario.

Algunos de los más usados son estos:

200 OK: Esto significa que todo ha ido bien y la solicitud se ha realizado con éxito.

201 Created: Este caso aparece por ejemplo cuando nos registramos como usuario en una web y todo ha ido bien.

204 No Content: En este caso la petición ha sido exitosa, pero no hay nada que devolver.

400 Bad Request: La petición que ha realizado el usuario es incorrecta, por ejemplo en un endpoint que tengamos que enviar un email, el formato sea inválido.

401 Unauthorized: Este caso ocurre cuando realizas una petición a un endpoint que requiere de autenticación.

403 Forbidden: A diferencia del estado 401, aquí si puedes estar logueado pero no tener los permisos necesarios para realizar la acción.

404 Not Found: El más mítico de todos 😂. Por ejemplo al intentar acceder a un endpoint o recurso inexistente.

500 Internal Server Error: Cuando ocurre cualquier error del lado del servidor.

Si quieres ver el listado con todos puedes hacerlo pinchando aquí.

BONUS.- Separar tu API en versiones

Casi se me olvida pero no xD. Con el paso del tiempo tu API puede ir evolucionando y te surgirán cambios importantes que pueden modificar el comportamiento de la API así como la información que envías y recibes del usuario como por ejemplo cambiar el tipo de autenticación de oauth a JWT. También puede ser que quieras cambiar el formato de las respuestas y seguir otro estándar.  Para evitar problemas, lo mejor es siempre crear tu API con un prefijo para diferenciar una versión de otra. Ejemplo:

api/v1/login
api/v2/login

De esta forma tú sigues teniendo tu versión 1 separada de la nueva versión y así podrás mantener la compatibilidad mientras tus usuarios se van migrando a la nueva versión y no dejarles con el culo al aire 😅.

Y eso es todo por este tutorial, si creéis que falta algún tip más que no deba faltar en la lista o queréis contar alguna anécdota con una API recordad que podéis escribirla en la caja de comentarios más abajo.

Espero que este post te ayude y como siempre, te recomiendo seguirme en Twitter para estar al tanto de los nuevo contenido. Ahora también puedes seguirme en Instagram donde estoy subiendo tips, tutoriales en vídeo e información sobre herramientas para developers.

Por último os dejo mi guía para aprender a trabajar con APIs donde explico todo el funcionamiento de una API, el protocolo HTTP y veremos como construir una API con arquitectura REST.

Nos leemos 👋.