7 consejos para crear mejores API Rest

Robert Sfichi el 02 Jun 2021

Construir API RESTful seguras y fáciles de usar, es una de esas tareas que dan muchos quebraderos de cabeza a los desarrolladores. Las API REST llevan mucho tiempo siendo el estándar del sector para facilitar la comunicación entre las aplicaciones back-end y front-end.

Nuestro equipo comprende la importancia de una API bien diseñada y ha reunido las mejores prácticas para ayudar a los desarrolladores en su camino hacia la creación de una API REST impecable.

¡Vamos a compartirlo todo con usted a través de los detalles más significativos!

Consejos para crear una API REST mejor

Algunos de los errores más comunes que cometen los desarrolladores cuando intentan crear una API REST son:

Documentación mal redactada
Arquitectura indefinida
Definiciones incoherentes de los puntos finales
Comunicación poco clara
Medidas de seguridad deficientes

No vivimos en un mundo perfecto. Es normal cometer errores. Sin embargo, antes de involucrarte en cualquier proyecto, debes tomar todas las precauciones y conocer todos los riesgos o errores que podrías cometer.

El mismo planteamiento se aplica a nuestro caso. Por eso nuestro equipo le ofrecerá en los párrafos siguientes un par de consejos basados en su experiencia personal y profesional.

1. Tomarse en serio la documentación

Documentar su API le ayuda a usted y a su equipo a comprender mejor el flujo de datos de la aplicación. Es inevitable que surjan problemas al crear una API. Cosas como actualizaciones de bibliotecas, versiones de la API o problemas de seguridad te harán desear haber escrito la documentación.

Al gestionar esto, también disminuye los recursos dedicados a la incorporación de nuevos desarrolladores de software remotos o internos y aumenta la facilidad con la que el equipo realiza actualizaciones y acciones de mantenimiento. Intenta darles la ventaja de construir sobre tu API incluso sin que entiendan del todo las tecnologías que has utilizado.

Afortunadamente, hoy en día es mucho más fácil crear documentación. Herramientas como Apiary, Swagger, Raml y muchas más ayudan a los desarrolladores a generar documentación en un instante. Siempre puedes inspirarte en documentación útil y bien escrita como The Rust Docs, GitHub Developer Docs, Ruby On Rails Guides, CasperJS o Moment.js.

2. Centrarse en la seguridad

Siempre debemos intentar que la comunicación entre el cliente y el servidor sea privada.

Los desarrolladores utilizan las API para crear sus servicios y transferir datos. Si una API está rota, expuesta o tiene importantes filtraciones de datos, definitivamente no será elegida por ningún desarrollador.

Intente validar los parámetros de la solicitud desde el principio. Implemente comprobaciones de validación y bloquee todas las solicitudes que no superen esa validación específica. Incluya validaciones para tipos de entrada, formatos y longitud. Acepte sólo ciertos métodos HTTP para puntos finales específicos e incluya marcas de tiempo para sus peticiones, de forma que sólo se acepten las que se realicen en un determinado periodo de tiempo. Esto previene algunos de los ataques de fuerza bruta que posiblemente afectarán a sus servidores.

Puedes llevar tu seguridad de autenticación un paso más allá implementando el marco de autenticación OAuth 2.0. Con la ayuda de aplicaciones de terceros, puedes crear un entorno más seguro para tus usuarios.

Nunca expongas información delicada, como nombres de usuario, contraseñas, claves API, etc., en las URL. Si realmente necesitas transferir esta información almacenándola en la URL, serializa de forma que sólo la máquina con la que necesitas comunicarte entienda los datos recibidos.

3. Elija el formato de datos adecuado para apoyar

La API es como un puente entre el servidor y el cliente. Por eso debemos transferir los datos en un formato adecuado para ambas partes. Esta elección influirá en la velocidad y el éxito de las peticiones.

Algunos de los formatos de datos más utilizados a la hora de crear una API son los datos directos, los datos de alimentación y los formatos de datos de base de datos.

Los formatos de datos directos son la mejor opción cuando se trata de interactuar con otras API. Algunos de los más utilizados son JSON, YAML y XML.

Los formatos de datos de feeds suelen utilizarse para publicar actualizaciones de servidores o aplicaciones web front-end y notificar a los usuarios los cambios realizados. Como probablemente ya habrás adivinado, estos formatos son los más utilizados en redes sociales, blogs o plataformas para compartir vídeos.

En la mayoría de los casos, los formatos de datos de bases de datos se utilizan para manipular datos entre distintas bases de datos o entre otras aplicaciones y bases de datos. SQL y CSV son dos de los formatos más utilizados en esta categoría.

4. Utilizar la paginación

Si la API que tú y tu equipo estáis construyendo va a devolver grandes cantidades de datos, puede ser una buena idea implementar la paginación. Siempre debemos evitar cualquier situación en la que el usuario pueda tener la oportunidad de hacer caer el servicio.

Recomendamos utilizar un límite por defecto para los datos devueltos y parámetros como limit y offset, tal y como se muestra a continuación: /usuarios?limit=30&offset=60.

La paginación también ofrece una gran oportunidad para ayudar a sus usuarios con la fatiga de decisión y elimina el ya despreciado scroll infinito.

5. Crear versiones para cada característica importante

El proceso de versionado de una API ayuda a los desarrolladores a mantener el control sobre la aplicación. Nunca se puede saber cómo afecta una nueva actualización a la usabilidad de cada usuario. Intenta siempre mantener copias de seguridad de las versiones antiguas de tu API, aunque la cambies por completo.

Veamos algunos ejemplos de cómo se puede versionar una API:

Coloque el número de versión directamente en la URL de la API: api.example.com/v1/users
Establezca cabeceras personalizadas para incluir el número de versión de la API: curl -H "API-version: 1.0 " https://api.example.com/users
Ajuste la cabecera accept para incluir el número de versión de la API: curl -H "Accept: application/vnd.example.v1+json " https://api.example.com/users
Añade el número de versión como parámetro de consulta: https://api.example.com/users?version=1

6. Utilizar métodos y códigos HTTP adecuados

Las API RESTful disponen de cuatro métodos para indicar qué harán los desarrolladores con los datos pasados.

Aunque pueda parecer lo más lógico, los desarrolladores tienden a utilizar sólo 2 de los siguientes métodos HTTP presentados. Es una práctica perfecta utilizar cada uno de ellos cada vez que la situación lo requiera.

GET - Utilice este método cada vez que necesite obtener un recurso o una colección de recursos.
POST - Los desarrolladores deben utilizarlo cada vez que necesiten crear un nuevo recurso o colección de recursos.
PUT - Este método se utiliza para actualizar información específica.
DELETE - Se explica por sí mismo. Nos ayuda a eliminar los recursos existentes o la colección de recursos.

Al igual que los desarrolladores prefieren utilizar sólo dos de los códigos HTTP mencionados anteriormente, la mayoría de las veces, sólo utilizan dos códigos HTTP. Esto puede traer muchos dolores de cabeza a ellos mismos y a todos los desarrolladores que trabajarán en el proyecto en el futuro.

200 OK - Este es el código más común con el que tropezamos como desarrolladores. O al menos eso esperamos. Se nos presenta siempre que una operación se ha realizado con éxito.
201 CREATED - El método POST presentado anteriormente va de la mano con este código HTTP, ya que se supone que alerta al cliente de que ha creado con éxito el recurso.
400 BAD REQUEST - Este es el código HTTP que aparecerá siempre que una petición no se haya realizado correctamente.
401 UNAUTHORIZED - Si necesitamos restringir el acceso de un usuario a una parte de nuestra aplicación, este debería ser el código HTTP que enviemos junto con el mensaje de error.
404 NOT FOUND - El código HTTP más común en todo Internet. Incluso las personas que no han estudiado desarrollo de software saben que el código HTTP 404 significa que no se han encontrado los recursos.
500 ERROR INTERNO DEL SERVIDOR - Se debe devolver este error siempre que el servidor no responda.

Como puede ver, todos los códigos HTTP se explican por sí mismos. Utilizar cada uno de ellos cuando la situación lo requiera puede ayudar a ahorrar mucho tiempo a largo plazo.

7. Asegúrese de que los mensajes de error son claros

Todos sabemos lo frustrante que es cuando recibimos un error y el mensaje es impreciso. No sólo no funciona el servicio, sino que ahora tenemos que averiguar de dónde viene el problema.

Debemos lanzar los mensajes de error correctos y el código de error HTTP más explícito para eliminar esta confusión.

Por ejemplo, si un usuario quiere crear una nueva cuenta pero el correo electrónico ya se utiliza en la plataforma, deberíamos devolver un código HTTP 400 con el mensaje "El correo electrónico ya existe". De esta forma, evitamos atender un número considerable de peticiones porque el usuario sabrá de qué se trata y no forzará el registro.

¿Qué aspecto tiene una API REST eficaz?

Aquí llegamos al final de una lista completa de consejos. Estos son sólo algunos de los métodos que puedes utilizar para crear una API REST más segura. Por supuesto, hay muchos más por ahí, pero si sólo utiliza los presentados anteriormente, probablemente estará por delante de la mayoría de los que ya están construidos.

Sin embargo, si no tiene tiempo ni paciencia para crear una API para sus proyectos de web scraping, ¿por qué no invertir en algo ya hecho? Nuestro equipo se ha esforzado por crear una de las API de web scraping más seguras y fáciles de usar. Estos son sólo algunos de los principios fundamentales que han utilizado para garantizar que nunca se produzcan violaciones de datos ni caídas de la API.

Si quieres intentarlo, puedes conseguir 1.000 llamadas a la API creando una cuenta gratuita y probando una de las API de raspado web con más éxito.

Comience ahora su viaje de raspado web.