Domino REST API (DRAPI): entendiendo Schema y Scope, y cómo se relacionan con el NSF, las vistas, los formularios y los agentes

Qué son el schema y el scope, y cómo se relacionan con el NSF, las vistas, los formularios y los agentes.

Un cliente solicitó una explicación clara de qué es realmente HCL Domino REST API. A continuación, la versión breve y auto explicativa.

Una base de datos NSF no habla REST de forma nativa. Un documento puede contener decenas de campos que no deben exponerse, un formulario puede incluir validaciones que solo tienen sentido dentro de Notes, y un agente es, en esencia, código arbitrario. Domino REST API (DRAPI) resuelve esto mediante dos elementos de diseño que deben comprenderse antes de exponer cualquier base de datos: el schema y el scope.

¿Qué es un Schema?

Un schema es un elemento de diseño (un JSON) almacenado dentro de los recursos de diseño del propio NSF. Su creación requiere acceso de Designer sobre la base de datos. El schema define qué se expone y cómo, y se conecta con tres elementos de diseño ya conocidos:

Formularios

El schema activa formularios de forma individual o en bloque y, para cada uno, define qué campos son legibles, cuáles son escribibles y cuáles quedan ocultos, además de reglas de validación. Es posible definir varios modos del mismo formulario — por ejemplo, un modo default utilizado para crear documentos, y un modo odata obligatorio para acceso vía OData. Cada modo puede tener su propia fórmula computada para determinar su disponibilidad según el usuario, sus grupos o sus roles, lo que permite mapear permisos a nivel de API sin depender únicamente de la ACL.

Vistas

El schema también referencia vistas de la base de datos. Al activarlas, sus colecciones de documentos quedan disponibles a través de endpoints de consulta, y las columnas devueltas en cada caso pueden personalizarse.

Agentes

Los agentes activados dentro de un schema se convierten en endpoints invocables por REST. Es la forma de exponer una pieza de lógica en LotusScript o Java como una acción de API.

Un detalle relevante: los documentos se asocian a un schema a través del valor de su campo form. Si un documento no tiene ese campo, o no coincide con ningún formulario activado, no aparecerá por la API — aunque puede seguir usándose internamente en vistas o agentes. Una misma NSF puede alojar varios schemas, lo que resulta útil para exponer distintos subconjuntos de datos o distintos niveles de acceso desde la misma base (por ejemplo, un schema "interno" con todos los campos y otro "partner" con un subconjunto reducido).

¿Qué es un Scope?

Mientras el schema define qué hay disponible, el scope define quién puede acceder y con qué nombre público. A diferencia del schema, el scope no vive dentro del NSF de la aplicación: su configuración se guarda en KeepConfig.nsf, en el servidor, y normalmente lo crea un administrador — no el desarrollador de la aplicación.

• Un scope apunta a un único schema en cada momento, aunque un mismo schema puede tener varios scopes distintos apuntándole (por ejemplo, para exponer los mismos datos bajo dos nombres o niveles de acceso diferentes).
• El nombre del scope es el que realmente se usa en las llamadas a la API, vía ?dataSource=<nombreDelScope>, para todas las operaciones CRUD. El cliente nunca dirige sus peticiones directamente al schema ni al NSF.
• El scope se conecta con OAuth: cuando un cliente se autentica, el scope de OAuth concedido determina a qué scopes de DRAPI (y por tanto a qué schemas, formularios, vistas y agentes) puede acceder. El administrador puede además limitar el nivel máximo de acceso, de modo que una aplicación nunca exceda lo autorizado aunque el schema técnicamente permita más.
• Un scope se puede reapuntar a otro schema más adelante — útil para versionar — pero renombrarlo una vez que hay clientes en producción rompe las integraciones existentes, así que conviene evitarlo.

La cadena completa: de la base de datos al cliente REST

Puesta toda junta, la relación sigue siempre esta secuencia: NSF → Schema → Scope → Aplicación OAuth → Cliente REST.

En la práctica: quién hace qué

La siguiente tabla resume la distribución habitual de responsabilidades en este proceso:

Para resumir

El NSF continúa siendo el mismo dato y la misma lógica de siempre. El schema determina qué forma adopta ese dato al salir por la API — qué campos de qué formularios, qué vistas, qué agentes — y cómo se comporta según quién realiza la solicitud. El scope es la puerta con nombre, gestionada por el administrador y protegida por OAuth, a través de la cual las aplicaciones externas acceden a ese schema. Esta separación es la diferencia entre exponer una API predecible y segura, o exponer accidentalmente todo el contenido de la base de datos.