Skip to content

api-access.es.mdx

Latest commit

 

History

History
137 lines (104 loc) · 5.75 KB

api-access.es.mdx

File metadata and controls

137 lines (104 loc) · 5.75 KB
Raw
title Acceso a la API
description APIs REST generadas, autenticación y claves de API para integraciones.

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:

Ruta Propósito
/api/v1/data/<object> CRUD generado para cada objeto (p. ej. /api/v1/data/account)
/api/v1/data/<object>/{id} Leer/actualizar/eliminar un registro individual
/api/v1/actions/<object>/<action> Invocar una acción declarativa (POST)
/api/v1/auth/* Autenticación (inicio de sesión, sesiones, OAuth, OIDC)
/api/v1/meta/* APIs de metadatos (objetos, campos, vistas) cuando está habilitado
/api/v1/keys Genera un sys_api_key de un solo uso para el usuario que llama (POST)
/api/v1/mcp Servidor Model Context Protocol sobre Streamable HTTP, cuando OS_MCP_SERVER_ENABLED=true
/api/v1/health Sonda de liveness/readiness (sin autenticación)

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:

Método Ideal para Cómo
Cookie de sesión Tráfico de navegador/UI Inicia sesión a través de /api/v1/auth/*; las cookies se limitan al nombre de host del proyecto
Token de acceso Bearer Móvil, SPA, trabajos de servidor de corta duración Intercambia credenciales en /api/v1/auth/sign-in/email y pasa Authorization: Bearer <token>
Clave de API Servidor a servidor, ETL, integraciones de larga duración Crea un sys_api_key y pásalo como token bearer

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:

Parámetro Significado
?limit= Tamaño de página (sujeto a un límite máximo en el servidor)
?offset= o ?cursor= Paginación
?filter= Filtrado en el servidor usando la sintaxis de filtros de ObjectQL
?sort= Expresión de ordenación (p. ej. -created_at)
?fields= Selección dispersa de campos

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.