Descubrimiento de la API

WebBlocks CMS expone una Content API orientada al descubrimiento para herramientas de IA y de operador de confianza. Una herramienta externa solo debería necesitar la URL base de la API del CMS y un token de la API del CMS para conocer los endpoints disponibles, los esquemas, los ejemplos y el flujo de trabajo de contenido seguro.

Para herramientas locales de IA o de operador, almacene la URL base de la API en lugar de la raíz pública del sitio:

La primera solicitud debería ser:

GET /webadmin/api es intencionadamente seguro para uso público. Sin un token Bearer válido devuelve únicamente un JSON mínimo de arranque:

• nombre del producto
• versión de la API
• authenticated: false
• un enlace a sí misma
• un mensaje breve que indica al llamante que se autentique

No debe devolver el inventario de endpoints, datos del sitio, contratos de contenido, vistas previas de tokens, hashes de tokens, detalles de usuarios, rutas locales ni elementos internos del servidor.

Con un token Bearer válido de la API del CMS, el descubrimiento devuelve:

• product: WebBlocks CMS
• cms_version y product_version
• api_version
• authenticated: true
• los nombres de las capacidades del token, sin el valor del token, su vista previa ni su hash
• los siguientes pasos recomendados
• enlaces para OpenAPI, la guía de IA, el contrato de contenido, los ejemplos, validate/apply, las páginas, la publicación de páginas, la publicación de bloques propiedad de la página, la navegación y los Shared Slots

La respuesta autenticada es el contrato de arranque canónico para las herramientas de IA y de operador. Las herramientas deberían seguir los enlaces devueltos en lugar de asumir acceso al sistema de archivos local del repositorio del CMS o a la documentación del paquete.

Para los planes de contenido, page.path y expected_path son rutas públicas canónicas de Page Translation, como /contact o /docs/internal-content-api. /p/... existe únicamente por compatibilidad pública heredada y las herramientas nuevas no deberían generarlo.

Los enlaces de descubrimiento actuales incluyen:

Los enlaces de validate/apply de contenido admiten los modos de plan create_draft_page y replace_existing_draft_page. Utilice GET /webadmin/api/content-contract para obtener la lista actual de modos y las reglas de seguridad.

Los enlaces de publicación requieren content.publish. POST /webadmin/api/pages/{page}/publish publica por defecto solo la página, con include_page_owned_blocks: false; no publica bloques en borrador salvo que la solicitud establezca explícitamente include_page_owned_blocks: true. La publicación en cascada de Shared Slots no está admitida y devuelve comentarios de validación en JSON. POST /webadmin/api/pages/{page}/publish-page-owned-blocks publica los bloques en borrador o en revisión propiedad de la página que sean elegibles, sin cambiar el estado del flujo de trabajo de la página.

GET /webadmin/api/examples/contact-page demuestra un bloque nativo contact_form. Evita intencionadamente el Trusted HTML, el marcado de formulario en bruto y los mecanismos alternativos mailto:, de modo que las herramientas puedan crear páginas de contacto en borrador seguras mediante el mismo contrato de bloques estructurado que utilizan los operadores en el administrador.

Los enlaces protegidos requieren:

Los tokens de la API del CMS exponen en el descubrimiento las capacidades seleccionadas al crear el token, de modo que las herramientas puedan conocer las acciones permitidas antes de intentar escrituras.

Capacidades estándar para la construcción de páginas:

• content.read
• content.validate
• content.apply
• navigation.write
• shared-slots.write

Las capacidades destructivas o de publicación son opciones avanzadas independientes y no se seleccionan de forma predeterminada:

• content.publish
• pages.delete

Las operaciones destructivas deben exigir una capacidad coincidente explícita y no deberían concederse a tokens normales de construcción de páginas.

Las herramientas normales de construcción de páginas no deberían dar por supuesto que la publicación está disponible. Si content.publish no está presente, las herramientas deberían detenerse antes de llamar a los endpoints de publicación e informar de que se requiere un token de operador de confianza con capacidad de publicación.

Los endpoints de la Content API devuelven errores en JSON en lugar de redirecciones del navegador, páginas de inicio de sesión o respuestas HTML de CSRF. Las cargas útiles de error incluyen enlaces de orientación cuando procede:

• api_discovery_url
• openapi_url
• documentation_url
• example_url

Comportamiento esperado de los estados:

• 401 para tokens ausentes, no válidos o revocados
• 403 para capacidades ausentes
• 422 para cargas útiles de contenido no válidas

Las respuestas de descubrimiento, OpenAPI, guía de IA, ejemplos y contrato de contenido no deben exponer valores reales de tokens, hashes de tokens, valores de .env, rutas del sistema de archivos local, rutas del servidor, trazas de pila, excepciones en bruto, elementos internos de la base de datos, listas de usuarios ni detalles privados del operador.

Las URL de vista previa como /webadmin/pages/{page}/preview son rutas de navegador o de administración. Requieren una sesión de navegador de administrador autenticada y no se abren con tokens Bearer de la API del CMS. Una redirección al inicio de sesión desde esa URL significa que falta la sesión de navegador; no es un fallo de autenticación de la Internal Content API.