La Interfaz de Programación de Aplicaciones (API) RESTful se introdujo en el propio año 2000, pero hasta la fecha no tenemos directrices o estándares establecidos para el desarrollo de las API. A lo largo de los años, los desarrolladores han probado varias formas de crear mejores soluciones de API REST. Algunas de ellas dieron en el blanco, mientras que otras lo pasaron por alto. La industria de desarrollo de software ha filtrado las mejores prácticas para el diseño de API de REST en los últimos 18-19 años.
¿Estás listo para construir mejores APIs?
La web está llena de opiniones con respecto a los diseños de las API, pero la mayoría de ellas son sólo discusiones académicas llenas de interpretaciones subjetivas en lugar de lo que realmente tiene sentido. Dejando toda la subjetividad a un lado, aquí están algunos de los factores y requisitos clave que le ayudarán a construir mejores APIs:
- Los estándares web deben ser utilizados estratégicamente, es decir, como y cuando sea necesario.
- Deben ser fáciles de usar y de acceder.
- El diseño debe ser sencillo, intuitivo y coherente, pero eficaz.
- Debe tener la flexibilidad de adoptar nuevas actualizaciones.
- La API debe ser eficiente y mantener un equilibrio con las necesidades del usuario.
Mejores prácticas y directrices para diseñar el API de RESTful
Los discutiremos uno por uno y trataremos de entenderlos mejor. Veamos las cosas que hay que tener en cuenta antes de construir una API:
1. Naming y convenciones
La API debe promover un uso claro. Utiliza tantas palabras como sea posible para evitar cualquier caso de ambigüedad para la persona que está leyendo el código, especialmente cuando se utiliza un nombre. Cada palabra contenida en un nombre debe proporcionar información destacada dondequiera que se utilice. En lugar de escribir el tipo de restricción, asigna nombres a todas las variables, parámetros y tipos asociados según sus funciones.
Utiliza los métodos y propiedades de las funciones libres y sigue las convenciones de los casos. Los métodos pueden tener el mismo nombre base cuando tienen el mismo significado básico, o funcionan en dominios separados.
2. Usa JSON
Dependiendo del tipo de tu aplicación y el propósito para el que necesitas la API, REST permite a un desarrollador utilizar varios formatos de salida como texto plano, JSON, CSV, RSS, HTML y XML. JSON es una opción ideal si tienes un servicio de cara al público y quieres hacerlo accesible a los usuarios a través de la API de REST en forma del formato de datos utilizado para la comunicación, tanto en el payload como en la respuesta. Además, la naturaleza genérica MIME de JSON facilita su uso.
3. Utilizar las direcciones URL y las acciones REST
Los principios REST, como la separación de tu API en recursos lógicos, han ganado amplia popularidad y han sido adoptados en gran medida por las empresas de desarrollo de aplicaciones. Estos recursos hacen uso de peticiones HTTP para ser manipulados donde varios métodos como GET, POST, DELETE, PUT, PATCH tienen significados específicos.
4. Usar el nesting de recursos para mostrar las relaciones de jerarquía
Todos los objetos de recursos tienen una jerarquía funcional y están relacionados entre sí. Por ejemplo, en una tienda, tenemos clientes y sus pedidos, ambos interrelacionados. Es una buena idea restringir el anidamiento a un nivel en REST API. Demasiados niveles anidados aumentan la complejidad y disminuyen la eficiencia. Sin embargo, la misma salida puede ser alcanzada por medio del filtrado.
5. Error Handling
Durante el desarrollo de una API, el tratamiento correcto de los errores es una de las prácticas en las que hay que centrarse, de las cuales el tratamiento estándar de los errores de HTTP es la más importante. Hay casi 71 códigos de estado HTTP diferentes disponibles para su uso, que están bien definidos y pueden reconocerse fácilmente. El tratamiento correcto de los errores de los estados HTTP es suficiente, pero siempre es mejor proporcionar información adicional y una explicación detallada para una buena experiencia del usuario.
6. Filtrado, clasificación, paginación y selección de campos
Algunas de las características más importantes de la utilización de una API son el filtrado, la clasificación y la paginación. El filtrado ayuda a reducir los resultados de la consulta utilizando parámetros específicos como la fecha, la ubicación, etc. Clasificar significa ordenar los resultados en un orden particular, es decir, ascendente o descendente según el parámetro elegido (por ejemplo, la fecha). El buscador filtra los resultados y muestra un número limitado de elementos coincidentes al decidir el rango de los resultados que se van a mostrar. La selección de campos permite utilizar varios parámetros para especificar cuáles quieres ver en los resultados de un determinado objeto.
7. SSL en todas partes – todo el tiempo
El uso de SSL reduce las posibilidades de ciberataques y garantiza la seguridad, ya que se puede acceder a tu API desde cualquier lugar del mundo y la mayoría de esas redes no están aseguradas ni encriptadas. Garantizar las comunicaciones cifradas y asegurar la autenticación, es decir, poder acceder con simples tokens sin firmar cada solicitud de API.
8. Versionado
Te permite hacer cambios en tu estructura de datos incluso los que son irreversibles. En los casos en los que tengas que gestionar múltiples APIs, te ayuda a implementar los cambios y mejorar el servicio de forma simultánea. Puedes implementar la versión en el encabezado de la solicitud o en la URI del endpoint según te parezca conveniente.
9. API endpoint
Un endpoint de la API se define como un punto en el que la API se conecta con el programa de software. En un endpoint de la API, el recurso siempre debe ser plural, y se puede acceder a cualquier instancia del recurso pasando el ID en la URL. En resumen, las rutas deben contener formas plurales de los recursos y el tipo de acción a realizar se define por el método HTTP.
10. Códigos de estado HTTP
Hay algunos códigos de estado significativos que tu API puede devolver. Estos códigos pueden utilizarse para ayudar a los usuarios de la API a enrutar sus respuestas. Algunos de los códigos de estado útiles son 200 (OK), 201 (Creado), 204 (Sin contenido), 304 (No modificado), 400 (Mala petición), etc.
11. Caching
Hay frameworks incorporados que ofrecen el HTTP para el almacenamiento en caché. Es necesario incluir algunos encabezados de respuesta de salida adicionales y tener que validarlos al recibir los encabezados de solicitud de entrada. Existen dos enfoques para ello. Uno es el ETag en el que se debe incluir un ETag de cabecera HTTP que tenga un hash o suma de comprobación de la representación mientras se genera una respuesta y el otro es el último modificado que funciona de forma similar al ETag junto con el uso de marcas de tiempo.
12. Autenticación
Una API RESTful ideal es apátrida, es decir, la autenticación de la solicitud no depende de cookies o sesiones. Cada solicitud debe tener asociadas algunas credenciales de autenticación. Las credenciales de autenticación pueden ser fácilmente simplificadas usando SSL, a un token de acceso aleatorio que se entrega al usuario. Es muy fácilmente accesible y explorable a través de un navegador.
13. Overriding el método HTTP
La Interfaz de Programación de Aplicaciones (API) necesita una forma de override los métodos HTTP para aumentar la accesibilidad a los clientes que sólo pueden trabajar con simples solicitudes GET y POST. No sigue ningún estándar alto sino el convencional de aceptar el encabezado de la petición X-HTTP-Method-Override con un valor de cadena que tiene uno de PUT, DELETE o PATCH.
14. Paginación
Se hace para manejar las respuestas fácilmente. El resultado de tener cientos de miles de páginas sería una tarea compleja de llevar a cabo mientras que podemos simplificarla estableciendo explícitamente un límite para asegurar el número de resultados deseados según el parámetro limitante.
