En el desarrollo de servicios web, el diseño y organización de una API REST son fundamentales para asegurar una comunicación eficiente y segura entre los distintos componentes de un sistema; así como asegurar la mantenibilidad en el tiempo, priorizando los tiempos de entrega. Este documento ofrece recomendaciones clave para estructurar una API REST, centradas en prácticas de seguridad, estandarización de paths, y manejo adecuado de datos tanto en solicitudes (requests) como en respuestas (responses).
Imagen 1: Lineamientos para desarrollo de APIs
Uso de Verbo POST por Seguridad
Es recomendable usar el verbo POST por razones de seguridad, evitando el envío de datos en los parámetros de la consulta (query params) y transportándolos en el cuerpo de la solicitud (body request). Esto es debido a cómo se empaquetan y cifran los datos durante el tránsito. En caso de usar el verbo GET, este debe emplearse únicamente para recuperar datos de configuración o parametrización, no para datos transaccionales ni de usuarios.
Formato del Path
El path debe seguir un formato de diseño API que indique la versión de la API, el tipo de objeto a manejar y la acción a implementar. Por ejemplo: /api/v1/items/create, donde v1 es la versión de la API, items es el tipo de objeto a manejar, y create es la acción a implementar. (ver imagen 1, sección path)
Manejo de Headers
Los headers deben contener datos que permitan la trazabilidad de logs y auditoría. (ver imagen 1, sección headers) Los datos especificados en la versión del documento son:
- ip: IP de la petición del Microservicio.
- channel: Canal de consulta.
- guidInvoke: Identificador del proceso del aplicativo o servicio que invoca.
- handleToken: API Key propio del servicio.
Estos headers deben imprimirse en los logs identificando los eventos mediante el identificador de proceso (guid), se puede a su vez complementar con la ip de la solicitud (se puede acceder por ejemplo con HttpServerRequest) ver imagen 2.
Imagen 2: Trazabilidad de logs
Manejo del Body Request
El Body Request debe contener los datos según lo requiera el servicio, siguiendo la convención de nombres en camel case. Es decir, los nombres se escriben en minúscula, y en caso de ser variables compuestas, se unifican mediante mayúsculas sin espacios. Ejemplo: variable simple «nombre», variable compuesta «nombreCompleto». (ver imagen 1, sección body request)
Manejo del Body Response
El Body Response debe incluir los siguientes datos mínimos (ver imagen 1, sección body response):
- codResponse: Códigos de respuesta controlados del servicio, indicando problemas o errores internos.
- msgUser: Mensaje de respuesta al usuario, el mensaje es controlado en español.
- msgTech: Mensaje técnico de respuesta, controlado o detallando el mensaje de stacktrace, que puede estar en inglés.
- result: Dependiendo del tipo de servicio, puede contener información transaccional o parametrizaciones. En caso de tener múltiples objetos de respuesta, se puede manejar como un vector con múltiples objetos. (ver imagen 3 y 4)
Imagen 3: Body Response cuando se manejan respuestas únicas
Imagen 4: Body Response cuando se manejan múltiple-respuestas
Consideraciones generales
Tanto Body Request, Body Response deben manejarse con Content Type tipo JSON.
Los servicios (y cada variable) deben estar documentados con detalle de que acción implementa. (ver imagen 5)
Imagen 5: Documentación ejemplo de variables
