Acceso a la API

Cada objeto declarado en el artefacto se expone a través de una API REST generada. Los mismos endpoints alimentan la UI, las integraciones y los scripts ETL de los clientes — no hay una "API de integración" separada que mantener.

URL base

https://<project-domain>/api/v1

Superficies destacadas:

El prefijo es /api/v1 de forma predeterminada (el basePath de la API, /api, más la version, v1) y es configurable en el stack de ObjectOS.

Controlar qué se expone

La exposición de la API se gobierna por objeto en el artefacto, no en la puerta de enlace:

• Establece apiEnabled: false en un objeto para mantenerlo fuera de la superficie REST por completo (sus rutas devuelven 404).
• Establece una lista blanca apiMethods (p. ej. ['get', 'list']) para hacer un objeto de solo lectura o restringir de otro modo qué operaciones son accesibles.

Ambos se aplican en la capa REST; consulta API REST → Restringir la superficie de la API.

Opciones de autenticación

Los clientes pueden autenticarse de tres maneras:

Las tres pasan por el mismo AuthPlugin y se resuelven en un contexto sys_user que el SecurityPlugin evalúa frente a los permisos y el acceso a registros.

Claves de API

Las claves de API son registros sys_api_key de primera clase. El valor de la clave en sí se almacena cifrado (hash) — solo el prefix y los metadatos permanecen consultables, de modo que una clave filtrada no puede reconstruirse a partir de la base de datos.

Emite una clave de dos maneras:

• Console — inicia sesión en Console → API Keys como administrador, elige el usuario propietario, opcionalmente establece una fecha de expiración y copia el secreto mostrado una sola vez.

• Endpoint de autoservicio — POST /api/v1/keys genera una clave para el llamante autenticado y devuelve el secreto en bruto exactamente una vez. La clave queda fijada al propio usuario del llamante, por lo que no puede usarse para suplantar otra identidad:

  curl -X POST https://app.example.com/api/v1/keys \
    -H "Authorization: Bearer <session-or-access-token>" \
    -H "Content-Type: application/json" \
    -d '{"name": "etl-pipeline"}'
  # → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" }

Pasa la clave en las solicitudes posteriores como token bearer, como cabecera x-api-key o como Authorization: ApiKey. Las API REST de datos y metadatos la autentican con el mismo verificador que MCP, bajo los permisos y la seguridad a nivel de registro del propietario de la clave:

curl https://app.example.com/api/v1/data/account \
  -H "x-api-key: os_pk_live_…"

Para revocar una clave, ejecuta la acción revoke_api_key en el registro sys_api_key correspondiente (también disponible en la UI de Console). La revocación surte efecto de inmediato en la siguiente solicitud.

Paginación, filtrado y ordenación

Los endpoints de listado generados aceptan los parámetros de consulta estándar de ObjectStack:

Consulta la documentación del framework para conocer la gramática completa de filtros — la gramática del runtime es la fuente de verdad.

Limitación de tasa

Usa la primitiva RateLimiter del framework (o tu ingress / gateway de API) para aplicar límites por IP y por identidad. Los buckets iniciales recomendados están documentados en Production readiness.

CORS

Si los clientes se ejecutan en un navegador desde un origen diferente, configura CORS en el ingress o mediante el middleware del runtime. No combines orígenes con comodín con solicitudes que incluyan credenciales.

OpenAPI / descubrimiento

El runtime puede servir un documento OpenAPI para la API REST generada cuando la capacidad correspondiente está incluida en la imagen. Las integraciones de los clientes deberían generar clientes a partir del documento OpenAPI por despliegue en lugar de construir URLs a mano, porque los nombres de los objetos y las rutas generadas siguen el artefacto desplegado.