Introducción General
Propósito del Manual
Regla
0.1: Este manual debe ser la guía prescriptiva para el diseño, desarrollo y mantenimiento de todas las APIs RESTful dentro de la organización. 0.2: Todos los equipos y desarrolladores involucrados en la creación o consumo de APIs REST deben adherirse a las reglas aquí establecidas.
Contexto: APIs REST
Regla
0.3: Las APIs REST deben ser diseñadas siguiendo los principios de Transferencia de Estado Representacional (REST) para asegurar la simplicidad, escalabilidad y alineación con los estándares de la web. 0.4: Se debe priorizar un diseño de API REST bien ejecutado para facilitar la integración entre sistemas, promover la mantenibilidad, la evolución y una experiencia de desarrollador (DX) positiva.
Audiencia y Alcance
Regla
0.5: Este manual está dirigido a desarrolladores backend, arquitectos de software, líderes técnicos y cualquier profesional involucrado en el ciclo de vida de las APIs REST. 0.6: Las reglas aquí contenidas aplican a todas las APIs REST de nueva creación y deben ser consideradas como objetivo para la refactorización de APIs existentes.
Objetivo del Manual
Regla
0.7: El objetivo principal de este manual es estandarizar y elevar la calidad de las APIs REST, asegurando que sean robustas, consistentes, seguras y fáciles de usar y mantener. 0.8: Se debe utilizar este manual como referencia para la toma de decisiones de diseño y como base para revisiones de código y validaciones de arquitectura de APIs REST.
Secciones
Directrices esenciales para el diseño de APIs REST.
Reglas para la correcta definición de URIs y nombres de recursos.
Uso adecuado de los verbos HTTP (GET, POST, PUT, DELETE, etc.).
Interpretación y uso correcto de los códigos de estado HTTP.
Normas para la representación de datos y formatos de serialización (ej. JSON).
Principios de HATEOAS para APIs auto-descriptivas.
Consideraciones y prácticas de seguridad para APIs REST.
Estrategias y mejores prácticas para el versionado de APIs.
Normas para la documentación clara y completa de APIs.
Manejo de paginación, filtrado y ordenamiento de resultados.
Estrategias para el manejo consistente y claro de errores.
Directrices para la implementación de estrategias de caching.
Implementación de límites de tasa para proteger la API.
Asegurando la idempotencia en operaciones que lo requieran.
Estrategias y mejores prácticas para el testing de APIs.
Consideraciones para el despliegue y la operación de APIs.