Autenticación y convenciones

Autenticación#

Cada solicitud lleva el token bearer de la autoridad compartida de Beyond, la misma identidad que usa Workspace:

GET /v1/session HTTP/1.1
Authorization: Bearer <token>

El CDN no guarda cuentas ni membresías. Una organización es un equipo de Workspace, y el CDN almacena solo identificadores opacos de organización y de usuario. Esta API nunca acepta tokens de invitado de aplicaciones privadas.

session.read responde el usuario que inició sesión, sus organizaciones, roles, capacidades de CDN y un resumen del plan. organization.read responde el contexto de una organización de quien llama. Cuando no se puede contactar a la autoridad, la respuesta es 502 UPSTREAM_UNAVAILABLE, nunca un rechazo ni una aprobación.

Roles y capacidades#

Los roles vienen de la autoridad: owner, admin, developer, viewer y none. El CDN es dueño de una tabla de capacidades sobre esos roles, y cada operación indica la capacidad que exige.

El rol none no tiene ninguna capacidad y oculta los recursos de la organización.

Dos operaciones exigen una capacidad que depende del entorno sobre el que actúan: la promoción y la reversión necesitan release.prepare para testing y release.promote para production. El contrato lo expresa de forma legible por máquina, x-beyond-capability-by, junto a x-beyond-capability.

Las negativas siguen una regla. Un recurso que quien llama no puede ver responde 404 NOT_FOUND, para no revelar su existencia. Un recurso visible sobre el que el rol no puede actuar responde 403 FORBIDDEN.

Las operaciones bajo /v1/platform pertenecen al backoffice de la plataforma. Exigen una capacidad de operador de plataforma que ningún rol de organización implica, y responden NOT_FOUND a todos los demás. No se documentan aquí.

Proveedores de registro#

Una organización puede resolver paquetes desde registros distintos del público, por ejemplo un registro privado para un ámbito de npm. Los ajustes pertenecen a la organización y los usan los registros que se ejecuten después. Los grafos fijados y los releases existentes nunca cambian.

La versión 1 lee registros compatibles con npm accesibles por Internet. Un registro accesible solo a través de una red privada o una VPN queda fuera de la versión 1: los workers llegan solo a direcciones públicas de Internet, y una dirección de registro que no puede serlo se rechaza al guardarla.

{provider} es default, para todo paquete sin un ajuste de ámbito, o un ámbito de npm como @acme.

{ "registry": "https://<registry host>", "token": "<registry token>" }

Quitar un proveedor hace que los paquetes de ese ámbito vuelvan a resolverse desde el registro predeterminado. Quitar un proveedor que no existe responde lo mismo.

La visibilidad pertenece al paquete#

Si un paquete es público se decide para cada paquete, no por la credencial con la que se leyó:

• Un paquete leído sin credencial es público.
• Un paquete leído con credencial es público solo cuando el mismo registro, consultado de forma anónima, responde la misma versión con la misma integridad y el mismo archivo comprimido, y el archivo comprimido en sí responde de forma anónima. Cualquier duda lo mantiene privado: un registro responde igual "no encontrado" y "no permitido" a un cliente anónimo.
• Un repositorio Git o una URL de archivo comprimido leídos con credencial son privados.

Un paquete público produce salidas públicas, aunque se haya usado tu token para leerlo, y se descarga sin el token. Un paquete privado se queda en tu organización, y también toda salida que lo lee, incluido el módulo de un paquete público que lo importa. Una aplicación privada no vuelve privadas sus dependencias públicas. Quitar un token no vuelve públicos los bytes que ya se retuvieron. Consulta Preparación e inventario.

Reintentos y cambios concurrentes#

Cada mutación indica cómo tolera un reintento:

Un Idempotency-Key cumple ^[A-Za-z0-9_.:-]{8,128}$, lo elige el cliente, es único por cada mutación que se quiere hacer y su ámbito es la organización de quien llama. Si una solicitud agota su tiempo de espera, envíala de nuevo con la misma clave: nunca generes una clave nueva para un reintento.

Paginación#

Las operaciones de listado aceptan limit (de 1 a 200, 50 de forma predeterminada) y after. Una página responde items y, cuando hay más, next. Envía next de vuelta como after. Los cursores son opacos.

Identificadores#

Errores#

Los fallos usan un solo sobre, con la misma forma que el del contrato de entrega. details reemplaza a diagnostics:

{ "error": { "code": "CONFLICT_VERSION", "message": "…", "details": { "current": 7 } } }

Los códigos son estables y nunca se traducen. Los motivos por los que un trabajo puede fallar son un vocabulario aparte que viaja dentro de documentos y eventos; consulta Trabajos.

Ningún GET inicia trabajo#

Ningún GET de esta API, ni ningún GET de la entrega publicada, inicia, reanuda o programa trabajo. Solo las operaciones POST explícitas crean trabajos. Leer un trabajo, un release o un inventario tantas veces como quieras es seguro.