Norma para la definición y publicación de APIs

Ámbito de aplicación de la norma

Esta norma es de aplicación tanto para nuevos desarrollos como mantenimientos que incluyan la creación de nuevas APIs dentro de una solución existente, independientemente de la infraestructura en la que se despliegue.

Las directrices que contiene la norma son independientes de la pila tecnológica utilizada para el desarrollo de la solución software. Los objetivos y características de la arquitectura no están vinculadas a la plataforma de publicación.

Por tanto, al publicar una API en una plataforma específica, deben tenerse en cuenta:

• Las directrices y estándares referidos en esta norma.
• Otras normas específicas a la plataforma de publicación utilizada

Puedes conocer en esta sección  cómo se marca la obligatoriedad de cumplimiento de las directrices que componen la norma.

Diseño

Reglas y convenciones relacionadas con el tipo de comunicación

DIR_01 Tipología de comunicación

OBLIGATORIO La API se diseñará según la tipología de comunicación y el protocolo con que se vaya a implementar.

DIR_02 Comunicación síncrona

OBLIGATORIO En el caso de comunicación síncrona, se usará OpenAPI en su versión 3.1.X como estándar para definir las APIs. Además, las comunicaciones deben de realizarse con alguno de los siguientes protocolos:

• APIs REST: Método estándar que DEBE ser utilizado en la mayoría de los proyectos, proporcionando consistencia y claridad en la definición de las APIs.
• GraphQL: Se puede RECOMENDAR su uso en proyectos que necesitan proporcionar métodos de búsqueda y exploración de los datos publicados, permitiendo consultas complejas y precisas para acceder a la información.
• gRPC síncrono: Se puede RECOMENDAR su uso en proyectos que requieren alta velocidad y eficiencia en la comunicación entre servicios, especialmente en entornos donde se prioriza la comunicación síncrona con bajo tiempo de latencia.

Se DEBE tener en cuenta que OpenAPI puede adaptarse para describir APIs basadas en GraphQL o gRPC, aunque es posible que no cubra todas las características específicas de estos protocolos. Por lo tanto, se RECOMIENDA realizar una evaluación detallada para asegurarse de que la descripción de la API se ajuste adecuadamente al protocolo utilizado. 

DIR_03 Comunicación asíncrona

OBLIGATORIO En el caso de comunicación asíncrona, se usará AsyncAPI como estándar para definir las APIs. Además, las comunicaciones deben de realizarse con alguno de los siguientes protocolos:

• SSE (Server-Sent Events): Se RECOMIENDA su uso en proyectos que requieren una transmisión unidireccional de eventos desde el servidor al cliente de manera eficiente y en tiempo real.
• WebSocket: Se RECOMIENDA su uso en proyectos que necesitan una comunicación bidireccional y en tiempo real entre el cliente y el servidor.
• gRPC asíncrono: Se RECOMIENDA su uso en proyectos que demandan una alta velocidad y eficiencia en la comunicación asincrónica entre servicios, especialmente en entornos donde se prioriza la comunicación asíncrona con bajo tiempo de latencia.

Se DEBE tener en cuenta que AsyncAPI puede adaptarse para diseñar APIs basadas en SSE, WebSocket o gRPC asíncrono, aunque es posible que no cubra todas las características específicas de estos protocolos. Por lo tanto, se RECOMIENDA realizar una evaluación detallada para garantizar que la descripción de la API se ajuste adecuadamente al protocolo utilizado.

Reglas y convenciones para la nomenclatura de las APIs y sus operaciones y para su versionado

DIR_04 Nombre de API

OBLIGATORIO El nombre de las APIs seguirán una serie de reglas estándar para su nomenclatura: 

• El nombre de la API DEBE ser descriptivo según el negocio al que dan soporte.
• El nombre de la API DEBE usar nomenclatura UPPERCASE.
• El nombre de la API DEBE seguir la nomenclatura <INT/EXT>_<PUB/PRV>_<NEGOCIO> siendo estos:
  • INT: servicios internos, publicados dentro de la RCJA
  • EXT: servicios publicados en internet 
  • PUB: servicios que no requieren seguridad para acceder a ellos
  • PRV: servicios que requieren de algún tipo de seguridad para acceder (delegada en la OTI o en el sistema proveedor)
• El contexto de la API DEBE usar nomenclatura kebab-case.
• El contexto de la API DEBE indicar claramente el negocio de la API.

DIR_05 Versionado de API

OBLIGATORIO Se creará una nueva versión de la API si se han realizado cambios que afectan a los consumidores de los servicios (no retrocompatibles), se han añadido endpoint o parámetros opcionales que no rompen con la funcionalidad existente o se han corregido errores que no cambian el contrato.

Las APIs siguen el versionado semántico, estructurado como MAJOR.MINOR.PATCH. Según el tipo de cambio, se debe incrementar uno de los tres:

PATCH (correcciones de errores menores - no cambia el contrato)

• Corrección de errores menores que no afectan la funcionalidad de la API.
• Pequeñas mejoras o ajustes que no cambian el contrato de la API.

MINOR (nuevas características retrocompatibles - cambia el contrato)

• Adición de nuevas características o funcionalidades que son retrocompatibles.
• Modificaciones en el contrato de la API que añaden nuevos endpoints o parámetros opcionales, pero no rompen la funcionalidad existente para los consumidores actuales.

MAJOR (cambios significativos y no retrocompatibles - cambia el contrato)

• Eliminar operaciones o acciones sobre un recurso. Ejemplo: Ya no se aceptan peticiones POST sobre un recurso. 
• Añadir nuevos parámetros de entrada obligatorios. Ejemplo: Ahora para dar de alta un recurso hay que enviar en el cuerpo de la petición un nuevo campo requerido.
• Modificar parámetros de entrada de opcional a obligatorio. Ejemplo: Ahora al crear un recurso Persona, el campo edad, que antes era opcional, ahora es obligatorio. 
• Modificar o eliminar un parámetro en operaciones (verbos sobre recursos) ya existentes. Ejemplo: al consultar un recurso ya no se devuelve determinado campo. Otro ejemplo: un campo que antes era una cadena de caracteres ahora es numérico. 
• Añadir nuevas respuestas en operaciones ya existentes. Ejemplo: ahora la creación de un recurso puede devolver un código de respuesta 412.

En caso de necesidad, para permitir la adaptación de los clientes a esta nueva versión de la API, se DEBE mantener en paralelo la versión anterior de la API durante el tiempo que se acuerde. Durante este tiempo se adaptarán los consumidores a la nueva versión.  Se permitirá la existencia de hasta dos versiones funcionando en paralelo.

Se RECOMIENDA marcar como deprecada la versión antigua de la API. 

Se RECOMIENDA que, al crear la nueva versión, se configure la opción de mantener la suscripción a la anterior versión con la nueva versión de API para facilitar la migración.

Se DEBE notificar a los usuarios suscritos a una API de la publicación de una nueva versión.

DIR_06 Revisión en el API Manager

OBLIGATORIO Se creará una nueva revisión de la API en el API Manager si se han realizado actualizaciones menores que no necesitan cambio de versión, pero permiten a los desarrolladores y consumidores probar cambios y nuevas implementaciones sin interrumpir el uso de la API actual.

Cambios menores en la implementación:

• Corrección de errores o mejoras en el backend.
• Optimización del rendimiento de la API.
• Ajustes en la configuración de la seguridad (sin cambios en los contratos).

Actualizaciones de documentación:

• Mejoras o correcciones en la documentación de la API.
• Adición de ejemplos más detallados o guías de uso.

Configuración de políticas y mediaciones:

• Cambios en las políticas de throttling o mediaciones que no afectan el contrato de la API.

Cambios en los endpoints del backend:

• Cambiar la URL del backend sin modificar el comportamiento o el contrato de la API.

Estas revisiones sirven de checkpoint en el tiempo, capturando el estado actual de la API cuando la revisión es creada. 

DIR_07 URI de las operaciones de la API

OBLIGATORIO Las URI de las operaciones seguirán una serie de reglas estándar para su nomenclatura:

• DEBEN usar solo los métodos GET, POST, PUT, PATCH y DELETE.
  • GET: obtener información del servidor
  • POST: crear un nuevo recurso y, por consiguiente, modifica el estado del servidor
  • PUT: actualizar un recurso
  • PATCH: actualizar parte de un recurso
  • DELETE: eliminar un recurso
• DEBEN de estar orientadas a la exposición de recursos y no de operaciones. /usuarios/{dni}/informes/{idInforme}
  • Se RECOMIENDA que la API gestione un único recurso pero puede gestionar varios si es necesario
• DEBEN usar nomenclatura de campos y parámetros lowerCamelCase. 
• DEBEN usar plurales en los nombres. /usuarios y no /usuario 
• Las URI NO DEBEN implicar una acción, por lo tanto, no se podrán usar verbos en ellas. 
• Han de ser únicas, NO DEBE haber más de una URI para identificar un mismo recurso.
• DEBEN mantener una jerarquía lógica según el aspecto de negocio que trate. 
  • Por ejemplo, la URI /facturas/25/clientes/007 no sería una URI correcta, ya que no sigue una jerarquía lógica de negocio ya que la factura está asociada al cliente y no al revés. 
  • Para el recurso factura con el identificador 25 del cliente 007, la siguiente URI sería la correcta: /clientes/007/facturas/25.
• Los filtrados de información de un recurso NO DEBEN hacerse en la URI. Se realiza concatenando atributos con QueryParam.
  • Incorrecto: /facturas/anio/2024/total/500-1000
  • Correcto: /facturas?anio=2024&total_min=500&total_max=1000
• Los QueryParam y PathParam NO DEBEN contener datos sensibles. En el caso de necesitar enviar datos sensibles, se enviarán dentro del body (si es una consulta, se DEBE configurar como un POST).
• Las fechas DEBEN tener el siguiente formato: YYYY[MM[DD[HH[mm[ss]]]]]
• NO DEBE incluir la versión en la uri: /usuarios/v1/, salvo en casos concretos que tendrán que obtener el visto bueno de la OTI.

Políticas relacionadas con la agrupación de recursos disponibles en distintas APIs

DIR_08 Agrupación de recursos

RECOMENDADO Se recomienda la creación de productos para agrupar recursos existentes de distintas APIs en lugar de crear una nueva API con dichos recursos. añadir documentación a la API publicada. Estos productos deberán contar con el visto bueno de la Oficina de Arquitectura de Soluciones.

Un producto API es un mecanismo de empaquetado que se puede utilizar cuando se necesita agrupar un conjunto de recursos de varias API y exponerlo como una interfaz API separada, que los suscriptores pueden consumir. Los productos API dan la capacidad de re-empaquetar API existentes en varias combinaciones para ofrecen una experiencia personalizada a sus suscriptores.

Los suscriptores ven el Producto API a través del API Portal como una entidad separada, independiente de las API con las que comparte sus recursos. Desde la perspectiva del suscriptor, el Producto API se verá y funcionará de la misma manera que cualquiera de las API estándar en el Portal de Desarrolladores.

Construcción

Reglas y convenciones sobre la construcción de los contratos de APIs

DIR_09 Definición de APIs REST

OBLIGATORIO La definición de APIs REST con OpenAPI 3 cumplirá los siguientes requisitos mínimos:

• Se DEBE indicar la descripción de la API de manera clara y los datos de contacto del autor.
• Se DEBE cumplimentar el campo descripción y resumen de los distintos objetos con el fin de facilitar su entendimiento, con texto auto explicativo, sin presuponer conocimientos y evitando argot técnico o de negocio.
• Se DEBEN estructurar los objetos definiendo componentes que puedan ser reutilizados, si es necesario y favorece la mantenibilidad, se definirán en un fichero separado y se hará referencia desde la propia especificación.
• Se DEBE indicar la tipología de todos los campos y si son requeridos o no, además de un ejemplo del valor o valores que pueden tomar. Si es un enumerado, se indicarán los posibles valores. 
• Se DEBEN indicar los caracteres permitidos en los campos tipo texto, preferiblemente mediante patrones.
• Se DEBE indicar la longitud mínima y máxima de los distintos tipos de campos, así como el tamaño mínimo y máximo de los arrays.
• Se DEBEN definir las posibles respuestas del servicio, indicando el código HTTP, la descripción y el cuerpo de la respuesta (en los casos en los que tenga).
• Se DEBE especificar el tipo de autenticación que usará la API.
• Se RECOMIENDA el uso de etiquetas para agrupar las operaciones.
• Se DEBE realizar la definición en castellano, tanto para las operaciones, recursos, parámetros y documentación.
• Se DEBE evitar el uso de nombres ambiguos o no descriptivos.
• Se DEBE mantener consistencia en la forma en que se nombran los parámetros:

{
 "Nombre_Ciudad": "...",
 "Provincia: "..."
}

{
 "Ciudad": "...",
 "Provincia: "..."
}
o
{
 "Nombre_Ciudad": "...",
 "Nombre_Provincia: "..."
}

Si la definición del API REST contiene operaciones internas (solo publicadas en RCJA) y externas (publicadas en internet), se RECOMIENDA crear dos definiciones OpenAPI para enviarlas al equipo de la OTI para que puedan ser publicadas de manera correcta.

DIR_10 Definición de APIs asíncronas

OBLIGATORIO La definición de APIs asíncronas con Async API 3 cumplirá los siguientes requisitos mínimos:

• Se DEBE indicar la descripción de la API de manera clara y los datos de contacto del autor.
• Se DEBE cumplimentar el campo descripción de los distintos objetos con el fin de facilitar su entendimiento.
• Se DEBEN indicar ejemplos del valor o valores que pueden tomar los distintos campos del mensaje, así como explicarlos.
• Se DEBEN estructurar los objetos definiendo componentes que puedan ser reutilizados, si es necesario y favorece la mantenibilidad, se definirán en un fichero separado y se hará referencia desde la propia especificación.
• Se RECOMIENDA el uso de etiquetas para agrupar las operaciones.
• Se DEBE realizar la definición en castellano, tanto para las operaciones, recursos, parámetros y documentación.

Normativa referente a la creación de prototipos para una validación temprana 

DIR_11 Creación de simulaciones

RECOMENDADO Se recomienda la creación de respuestas simuladas similares a lo que realmente devolverá el servicio para facilitar la comprensión del contenido de las respuestas a los desarrolladores que se integren.

Las plataformas de API Management suelen incluir opciones para la creación de simulaciones con respuestas falsas para probar las APIs.

Existen herramientas en línea que permiten generar respuestas simuladas y obtener una URL que sirve como punto de conexión de prueba de la API.

Normativa referente a documentación

DIR_12 Documentar la API

RECOMENDADO Se recomienda añadir documentación a la API publicada.

Es posible añadir documentación, ya sea en línea, mediante enlaces o documentos, que facilite la comprensión de la funcionalidad de la API. Esta documentación puede ir desde flujos de trabajo, ‘how to’ de la propia API e incluso códigos de ejemplo de uso.

DIR_13 Idioma de la documentación

OBLIGATORIO La documentación estará redactada en castellano. 

Seguridad

Reglas de resiliencia y destinadas a evitar la sobrecarga del servidor de APIs y de los backends

Las políticas de resiliencia se consideran como una parte integral de la arquitectura y el diseño de sistemas distribuidos. Es necesario implementar un conjunto diverso de políticas de resiliencia en cada servicio para mitigar una variedad de posibles fallas y errores.

DIR_14 Limitación del tiempo de respuesta

OBLIGATORIO Se definirán políticas de timeout para establecer límites de tiempo de respuesta para las solicitudes a servicios, evitando los bloqueos y manteniendo la capacidad de respuesta del sistema.

Por defecto, el timeout estará configurado en 30 segundos.

DIR_15 Balanceo de las solicitudes

RECOMENDADO Se recomienda establecer políticas de Load Balancing para que distribuyan las solicitudes entrantes entre múltiples instancias de un servicio para evitar la sobrecarga en cualquier instancia individual.

Las plataformas de gestión de API permiten realizar un balanceo de carga estableciendo distintos endpoints a los que balancear. No obstante, es necesario consultar el Modelo de Despliegue correspondiente a la tecnología con la que se construya el backend para saber si ya está configurada a nivel backend.

DIR_16 Uso de caché en las respuestas

OBLIGATORIO Se hará uso del cacheo de respuestas para mejorar el tiempo de respuesta y minimizar la carga del backend.

Permitir el cacheo de respuestas permite que, ante una misma petición, la respuesta siempre sea la misma durante el tiempo de vida configurado de la caché. Esto implica que la carga del backend sea menor ya que hay peticiones que no le van a llegar y que el cliente que realiza una misma petición varias veces seguidas, obtenga siempre el mismo resultado. 

Por defecto, está configurada en 15 minutos.

DIR_17 Limitación del uso

OBLIGATORIO Se configurarán políticas de limitación de uso de la API.

Para proteger las API de tipos comunes de ataques de seguridad, como de ataques de denegación de servicio (DoS) y para regular el tráfico según la disponibilidad de infraestructura, hay que limitar el número de peticiones exitosas a una API durante un período determinado.

Por defecto, se DEBE configurar un límite de 100 peticiones por minuto.

Pruebas

Políticas de pruebas sobre sistemas de gestión de APIs

DIR_18 Pruebas de validación

OBLIGATORIO Se realizará una colección de pruebas de validación de la API 

Las pruebas unitarias son la primera línea de defensa en la detección de errores, por lo que es muy importante que cubran todos los servicios disponibles. El tener una colección de pruebas de todas las operaciones de una API, permite encontrar posibles errores fácilmente tras cambios en el backend.

Normas relacionadas

La construcción de un microservicio implica el cumplimiento de esta norma y las normas transversales que se apliquen:

• Norma de uso del repositorio de código corporativo
• Norma para el alineamiento con la pila tecnológica de la ADA
• Norma para el desarrollo seguro
• Norma para la observabilidad
• Norma para el desarrollo de microservicios

Estándares

El siguiente listado muestra los estándares que se aplican a la arquitectura de microservicios. Puede consultarse la descripción de cada estándar en la siguiente página

Definición de servicios y eventos

• Open API
• Async API
• XML Schema

Comunicaciones

• API RESTful
• GraphQL
• gRPC
• WebSockets
• Server-Sent Events (SSE)

Seguridad

• SSOWEB(SAML 2.0)
• HTTPS/SSL
• OAuth2