7 consejos para crear mejores API REST

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

• Documentación mal redactada
• Arquitectura indefinida
• Definiciones de puntos finales incoherentes
• 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 enfoque se aplica a nuestro caso. Por eso, nuestro equipo te ofrecerá un par de consejos basados en su experiencia personal y profesional en los siguientes párrafos.

Documentar tu API te ayuda a ti y a tu equipo a comprender mejor el flujo de datos de la aplicación. Inevitablemente, surgirán problemas al crear una API. Cosas como las actualizaciones de bibliotecas, el control de versiones de la API o los problemas de seguridad te harán desear haber redactado la documentación.

Al gestionar esto, también reduces los recursos dedicados a la incorporación de nuevos desarrolladores de software, ya sean remotos o internos, y facilitas las tareas de actualización y mantenimiento del equipo. Intenta ofrecerles la ventaja de poder desarrollar sobre tu API incluso sin que comprendan 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 otras ayudan a los desarrolladores a generar documentación en un instante. Siempre puedes inspirarte en documentación útil y bien redactada como The Rust Docs, GitHub Developer Docs, Ruby On Rails Guides, CasperJS o Moment.js.

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

Los desarrolladores utilizan API para crear sus servicios y transferir datos. Si una API no funciona, queda expuesta o sufre brechas de datos importantes, ningún desarrollador la elegirá.

Intenta validar los parámetros de las solicitudes desde el principio. Implementa comprobaciones de validación y bloquea todas las solicitudes que no superen esa validación específica. Incluye validaciones para los tipos de entrada, los formatos y la longitud. Acepta solo determinados métodos HTTP para puntos finales específicos e incluye marcas de tiempo en tus solicitudes, de modo que solo se acepten aquellas realizadas dentro de un intervalo de tiempo concreto. Esto evita algunos de los ataques de fuerza bruta que podrían afectar a tus servidores.

Puedes llevar la seguridad de tu 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 exponga información delicada, como nombres de usuario, contraseñas, claves API, etc., en las URL. Si realmente necesita transferir esta información almacenándola en la URL, serialice los datos de forma que solo la máquina con la que necesita comunicarse pueda entender los datos recibidos.

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 solicitudes.

Algunos de los formatos de datos más utilizados al crear una API son los datos directos, los datos de feeds y los formatos de datos de bases de datos.

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

Los formatos de datos de feed se suelen utilizar para publicar actualizaciones desde servidores o aplicaciones web front-end y notificar a los usuarios que se han realizado estos cambios. Como probablemente ya habrás adivinado, estos formatos se utilizan con mayor frecuencia en redes sociales, blogs o plataformas para compartir vídeos.

En la mayoría de los casos, los formatos de datos de base de datos se utilizan para manipular datos entre diferentes 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.

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

Recomendamos utilizar un límite predeterminado para los datos devueltos y parámetros como limit y offset, tal y como se muestra aquí: /users?limit=30&offset=60.

La paginación también ofrece una gran oportunidad para ayudar a tus usuarios a evitar la fatiga de decisión y elimina el ya tan denostado desplazamiento infinito.

El proceso de versionado de una API ayuda a los desarrolladores a mantener el control sobre la aplicación. Nunca se sabe cómo afectará una nueva actualización a la usabilidad de cada usuario. Intenta siempre mantener una copia de seguridad de las versiones antiguas de tu API, incluso si la cambias por completo.

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

• Coloca el número de versión directamente en la URL de la API: api.example.com/v1/users
• Establece encabezados personalizados para incluir el número de versión de la API: curl -H “API-version: 1.0” https://api.example.com/users
• Ajusta el encabezado «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

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 solo 2 de los métodos HTTP que se presentan a continuación. Lo ideal es utilizar cada uno de ellos cada vez que la situación lo requiera.

• GET: utiliza este método cada vez que necesites recuperar un recurso o una colección de recursos.
• POST: los desarrolladores deben utilizarlo cada vez que necesiten crear un nuevo recurso o una colección de recursos.
• PUT: este método se utiliza para actualizar datos específicos.
• DELETE — Es bastante evidente. Nos ayuda a eliminar recursos existentes o colecciones de recursos.

Al igual que los desarrolladores prefieren utilizar solo dos de los códigos HTTP mencionados anteriormente, la mayoría de las veces solo utilizan dos códigos HTTP. Esto puede acarrear muchos quebraderos de cabeza para ellos mismos en el futuro y para todos los desarrolladores que trabajen en el proyecto más adelante.

• 200 OK — Este es el código más común con el que nos encontramos como desarrolladores. O al menos eso esperamos. Se nos muestra siempre que una operación se ha realizado con éxito.
• 201 CREATED — El método POST presentado anteriormente va de la mano de este código HTTP, ya que se supone que debe alertar al cliente de que ha creado el recurso con éxito.
• 400 BAD REQUEST — Este es el código HTTP que aparecerá siempre que una solicitud no se haya realizado con éxito.
• 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 puedes ver, todos los códigos HTTP son bastante claros. Usar cada uno de ellos cuando la situación lo requiera puede ayudar a ahorrar mucho tiempo a largo plazo.

Todos sabemos lo frustrante que es recibir un error y que el mensaje sea ambiguo. No solo el servicio no funciona, sino que ahora tenemos que averiguar de dónde viene el problema.

Debemos mostrar los mensajes de error adecuados 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 está en uso en la plataforma, debemos devolver un código HTTP 400 con el mensaje «El correo electrónico ya existe». De esta forma, evitamos tener que gestionar un número considerable de solicitudes, ya que el usuario sabrá cuál es el problema y no forzará el registro.

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

Sin embargo, si no tienes el tiempo ni la paciencia para crear una API para tus 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 solo algunos de los principios fundamentales que han utilizado para garantizar que nunca se produzcan fugas de datos ni interrupciones en el servicio de la API.

Si quieres probarla, puedes obtener 1000 llamadas a la API creando una cuenta gratuita y probando una de las API de web scraping más exitosas.

¡Empieza ya tu aventura en el web scraping!