T3.4: Creates REST Services

Resumen

InterSystems IRIS proporciona un framework completo para crear servicios web RESTful que siguen la especificación OpenAPI 2.0. Un servicio REST completo consiste de cuatro componentes trabajando juntos: la clase de especificación, clase dispatch, clase de implementación, y aplicación web.

Clase de Especificación

La clase de especificación (extendiendo %REST.Spec) sirve como la definición de contrato, conteniendo un bloque XData con la especificación OpenAPI 2.0 completa en formato JSON. Esta especificación define todos los endpoints, métodos HTTP, parámetros, formatos de solicitud/respuesta, y documentación.

Clase Dispatch

La clase dispatch (extendiendo %CSP.REST) es automáticamente generada desde la especificación y nunca debería editarse manualmente. Maneja enrutamiento de solicitud HTTP, valida solicitudes entrantes contra la especificación, realiza verificación de content-type, e invoca los métodos de implementación apropiados.

Clase de Implementación

La clase de implementación (extendiendo %REST.Impl) es donde desarrolladores escriben la lógica de negocio real. Contiene métodos stub inicialmente generados desde la especificación que desarrolladores luego completan con consultas de base de datos, cálculos, y transformaciones de datos. La superclase %REST.Impl proporciona métodos de utilidad esenciales como %SetStatusCode(), %SetHeader(), %WriteResponse(), y %ReportRESTError() para controlar respuestas HTTP.

Configuración de Aplicación Web

La configuración de aplicación web en el Management Portal conecta todo junto, especificando la clase dispatch, habilitando funcionalidad REST, y controlando configuraciones de seguridad.

Convención de Nomenclatura y Regeneración de Clase

InterSystems aplica una convención de nomenclatura estricta: dado nombre de aplicación "myapp", las clases se nombran myapp.spec, myapp.disp, y myapp.impl, con la ruta de aplicación web predeterminada /csp/myapp. Cuando la clase de especificación se recompila, la clase dispatch regenera automáticamente y la clase de implementación actualiza inteligentemente, preservando código de desarrollador mientras agrega nuevos métodos stub para nuevos endpoints.

Resumen

InterSystems IRIS soporta dos enfoques distintos para desarrollo de servicio REST, cada uno con casos de uso y compensaciones específicas.

Enfoque Specification-First (Recomendado)

El enfoque specification-first, introducido en IRIS 2019.2 y ahora recomendado, comienza con crear u obtener un documento de especificación OpenAPI 2.0 que define formalmente el contrato API REST. Esta especificación JSON describe todos los endpoints, métodos HTTP, parámetros, esquemas de solicitud/respuesta, content types, y documentación legible para humanos. Desarrolladores usan las herramientas de gestión API (servicio /api/mgmnt, rutina ^%REST, o clase %REST.API) para generar la estructura de tres clases automáticamente. Las ventajas mayores incluyen generación automática de código reduciendo errores manuales, soporte integrado para regeneración cuando especificaciones cambian, documentación interactiva vía Swagger UI, separación clara de contrato de implementación, y colaboración más fácil entre diseñadores API e implementadores.

Enfoque Code-First (Legacy)

El enfoque code-first, usado antes de 2019.2 y aún soportado, involucra crear manualmente una clase que extiende %CSP.REST directamente, definiendo un bloque XData URLMap que mapea patrones URL a métodos ObjectScript, e implementando esos métodos en la misma clase o clases de implementación separadas. Este enfoque ofrece desarrollo inicial más rápido para servicios simples, sin requisito de aprender formato de especificación OpenAPI, y control completo sobre lógica de enrutamiento y manejo de error. Sin embargo, carece de generación automática de documentación, requiere actualizaciones manuales para todos los cambios, y no se integra con todas las herramientas de gestión API.

Migración y Mejores Prácticas

Para servicios codificados manualmente, InterSystems proporciona utilidades para generar especificaciones OpenAPI retroactivamente para propósitos de documentación. Mejores prácticas recomiendan specification-first para servicios de producción, colaboración de equipo, APIs públicas, y servicios requiriendo documentación formal. Code-first puede ser apropiado para prototipos internos, endpoints de utilidad simples, o servicios con requisitos de enrutamiento inusuales no fácilmente expresados en formato OpenAPI. Organizaciones también pueden adoptar enfoques híbridos, comenzando con codificación manual para prototipado rápido y migrando a specification-first cuando servicios maduran.

Resumen

InterSystems IRIS proporciona herramientas de gestión API completas que habilitan a desarrolladores y administradores controlar, monitorear, y descubrir servicios REST a través de su ciclo de vida.

El Servicio /api/mgmnt

El servicio /api/mgmnt es en sí mismo una API REST que proporciona endpoints para gestión completa de servicio. Endpoints clave incluyen POST /api/mgmnt/v2/:namespace/:application para crear nuevos servicios REST desde especificaciones OpenAPI, GET /api/mgmnt/v2/:namespace/:application para recuperar especificaciones de servicio en formato JSON, DELETE /api/mgmnt/v2/:namespace/:application para remover servicios, y GET /api/mgmnt/v1/:namespace/restapps para listar todas las aplicaciones web habilitadas con REST. Este servicio acepta especificaciones OpenAPI 2.0 en formato JSON vía cuerpos de solicitud POST y puede ser invocado desde herramientas como Postman, curl, o scripts personalizados.

La Rutina ^%REST

La rutina ^%REST proporciona una interfaz de línea de comando más simple accesible desde el terminal IRIS, útil para operaciones rápidas durante desarrollo sin requerir herramientas HTTP.

La Clase %REST.API

La clase %REST.API ofrece acceso programático a la misma funcionalidad, con métodos de clase como CreateApplication(), UpdateApplication(), DeleteApplication(), GetAllRESTApps(), y GetRESTApps() que retornan valores %Status para manejo de error. Estos métodos retornan %ListOfObjects conteniendo instancias %REST.Application con información detallada sobre cada servicio.

Capacidades de Descubrimiento

Capacidades de descubrimiento son particularmente valiosas en despliegues grandes, permitiendo a administradores inventariar todos los servicios REST, identificar qué namespaces contienen qué servicios, recuperar especificaciones OpenAPI para documentación, y verificar configuraciones de aplicación web. Las herramientas soportan tanto servicios specification-first (con clases .spec) como servicios codificados manualmente (sin clases .spec), aunque algunas operaciones como regeneración solo funcionan con servicios specification-first.

Logging e Integración

Logging puede configurarse para rastrear operaciones de gestión API, timestamps de creación de servicio, cambios de especificación, y errores durante generación de código. Estos logs son esenciales para solución de problemas de despliegue y mantener trazas de auditoría. Herramientas de terceros se integran bien con estas APIs de gestión, incluyendo Swagger Editor para desarrollo y validación de especificación, colecciones Postman para probar endpoints, y pipelines CI/CD para despliegue automatizado. Mejores prácticas incluyen usar /api/mgmnt para despliegues automatizados e integración con herramientas externas, usar ^%REST para sesiones de desarrollo interactivas, y usar %REST.API cuando se construyen utilidades de administración personalizadas o dashboards.

Resumen

Asegurar servicios REST en InterSystems IRIS involucra múltiples capas de autenticación y autorización trabajando juntas para proteger datos y operaciones sensibles.

Métodos de Autenticación

Para autenticación, IRIS soporta tres mecanismos primarios. Headers de autenticación HTTP son el enfoque recomendado para servicios REST de producción, soportando tanto autenticación Basic (username:password codificado base64) como autenticación Bearer token (tokens de acceso JWT o OAuth) enviados en el header Authorization. Autenticación de sesión web permite credenciales en parámetros de consulta URL pero es menos segura y debería evitarse para producción. OAuth 2.0 proporciona autenticación de grado empresarial con control de acceso basado en token.

Implementación OAuth 2.0

Para implementar OAuth 2.0, administradores deben configurar la instancia IRIS como un servidor de recursos OAuth 2.0, configurar la aplicación web del servicio REST para usar autenticación delegada, y crear una rutina ZAUTHENTICATE en el namespace %SYS que valida tokens OAuth entrantes y los mapea a cuentas de usuario IRIS. InterSystems proporciona una rutina de muestra (REST.ZAUTHENTICATE.mac) en el repositorio GitHub Samples-Security que desarrolladores pueden copiar y personalizar. Esta rutina extrae el token de acceso de solicitudes, lo valida contra el servidor de autorización, recupera claims de usuario, y establece el contexto de seguridad IRIS.

Autorización con RBAC

Para autorización (controlar qué usuarios autenticados pueden hacer), IRIS usa control de acceso basado en roles (RBAC) con recursos y privilegios. Desarrolladores especifican privilegios requeridos usando la propiedad de extensión OpenAPI x-ISC_RequiredResource en la clase de especificación. Esta propiedad puede aparecer en el objeto info para proteger el servicio entero o en objetos de operación individuales para proteger endpoints específicos. El valor es un array de pares resource:mode como ["PatientData:READ","Prescriptions:WRITE"]. Cuando la especificación compila, estos requisitos son embebidos en la clase dispatch, que automáticamente realiza verificaciones de autorización antes de invocar métodos de implementación. Si usuarios carecen de privilegios requeridos, reciben respuestas HTTP 403 Forbidden. Adicionalmente, el parámetro SECURITYRESOURCE de %CSP.REST proporciona protección a nivel de clase, requiriendo acceso a recurso específico antes de que cualquier endpoint pueda ser invocado.

Seguridad de Aplicación Web y Mejores Prácticas

La configuración de aplicación web en el Management Portal proporciona otra capa de seguridad, controlando métodos de autenticación permitidos (Password, Unauthenticated, Kerberos, Delegated), habilitando requisitos SSL/TLS, y estableciendo políticas de contraseña. Mejores prácticas incluyen siempre usar HTTPS en producción para encriptar credenciales en tránsito, implementar OAuth 2.0 para APIs públicas y arquitecturas de microservicios, usar x-ISC_RequiredResource para protección de endpoint de grano fino, rotar regularmente claves de firma JWT, implementar flujos de trabajo de expiración y refresh de token, registrar fallos de autenticación para monitoreo de seguridad, y nunca embeber credenciales en código del lado del cliente o URLs.

Resumen

Documentación efectiva de API REST es crítica para adopción de desarrollador, mantenimiento, y éxito a largo plazo. El enfoque specification-first de InterSystems IRIS inherentemente soporta documentación completa a través del formato de especificación OpenAPI 2.0. La especificación sirve como contrato ejecutable y documentación legible para humanos.

Campos Description de OpenAPI

Desarrolladores deberían poblar todos los campos description a través de la especificación OpenAPI, incluyendo el objeto info (resumen API, versión, información de contacto, licencia), objetos operation (qué hace cada endpoint, comportamiento esperado, casos límite), objetos parameter (propósito de cada parámetro, rangos de valor válidos, valores predeterminados), objetos response (escenarios de éxito y error, códigos de estado, estructuras de respuesta), y objetos schema (modelos de datos, significados de campo, restricciones). Las extensiones x-ISC usadas por InterSystems también deberían documentarse para mantenedores.

Integración Swagger UI

Una vez la especificación está completa, Swagger UI proporciona documentación interactiva que desarrolladores pueden acceder a través de navegadores web. Para configurar Swagger UI, organizaciones pueden alojar su propia instancia o usar el Swagger Editor público en línea. La documentación muestra todos los endpoints organizados por tags, muestra métodos HTTP con codificación de color apropiada, permite a desarrolladores ejecutar solicitudes de prueba directamente desde la documentación, muestra ejemplos de solicitud/respuesta con resaltado de sintaxis, y muestra requisitos de parámetro y tipos de datos.

Acceso a Especificaciones Programáticamente

InterSystems IRIS expone especificaciones OpenAPI a través del endpoint GET /api/mgmnt/v2/:namespace/:application, que retorna la especificación completa en formato JSON. Este endpoint puede usarse directamente con Swagger UI ingresando la URL en la caja exploradora de Swagger UI. Para documentación estática, herramientas de terceros pueden generar documentación HTML, PDF, o Markdown desde especificaciones OpenAPI, útil para distribución offline o embeber en conjuntos de documentación más grandes.

Mejores Prácticas de Documentación

Mejores prácticas de documentación adicionales incluyen mantener un changelog en el campo info.description rastreando cambios de versión API, usar valores operationId significativos que describen operaciones claramente, proporcionar ejemplos realistas en descripciones de parámetro y respuesta, documentar todos los códigos de estado HTTP posibles incluyendo condiciones de error, explicar requisitos de autenticación explícitamente, incluir información de rate limiting y quota si aplicable, proporcionar ejemplos de código para operaciones comunes en múltiples lenguajes, y mantener especificaciones separadas para diferentes versiones API. La clase de especificación misma debería incluir comentarios ObjectScript explicando lógica de negocio compleja en la clase de implementación, particularmente optimización de consulta de base de datos, reglas de transformación de datos, y estrategias de manejo de error. Para servicios REST codificados manualmente sin clases de especificación, desarrolladores aún pueden generar especificaciones OpenAPI usando las herramientas de gestión API para propósitos de documentación. Organizaciones deberían establecer procesos de revisión de documentación, asegurando que especificaciones sean actualizadas cuando endpoints cambian, revisando documentación para claridad y completitud antes de releases, y recopilando retroalimentación de consumidores API para mejorar calidad de documentación. Servicios REST bien documentados reducen carga de soporte, aceleran incorporación de desarrollador, minimizan errores de integración, y mejoran tasas de adopción API generales.