Saltar a contenido

API Documentation Platform

Estado: VERDE SANDBOX PUBLICADO
Scope: global
tenant_id: global
Owner: OpenClaw Platform Governance
Fuente de verdad: docs/architecture/API-DOCUMENTATION-PLATFORM.md

Objetivo

Definir y operar la plataforma oficial para documentar, visualizar y probar APIs de forma simple, moderna y segura, usando Scalar sobre contratos sanitizados, sin publicar endpoints reales ni exponer datos productivos.

Esta etapa ya tiene una primera implementacion sandbox publicada en https://developers.alpuntodeventa.com.ar y mantiene la separacion estricta entre documentacion publica y runtime interno real.

Que problema resuelve

La API Platform ya define como deberan nacer las APIs multi-tenant futuras, pero todavia faltaba la capa oficial para que equipos internos, terceros autorizados y agentes puedan:

  • descubrir que APIs existen o existiran
  • entender rapidamente para que sirve cada endpoint
  • ver contratos OpenAPI consistentes
  • probar APIs en entornos controlados
  • distinguir entre alcance global y alcance tenant
  • evitar documentacion dispersa, incompleta o insegura

Relacion con API Platform

La API Documentation Platform no reemplaza a la API Platform.

Relaciones clave:

  • la API Platform define como se exponen APIs futuras
  • la API Documentation Platform define como se documentan, visualizan y prueban esas APIs
  • toda API futura aprobada por la API Platform debe terminar publicada aqui con contrato OpenAPI
  • esta capa depende de los contratos, permisos, scopes y reglas de seguridad definidos en API-PLATFORM.md

Documento rector relacionado:

Relacion con Data Foundation

La Data Foundation define dominios, tenant_id, trazabilidad y seguridad futura del dato. La API Documentation Platform usa ese contrato para evitar documentar APIs ambiguas o sin ownership de datos.

Impactos concretos:

  • toda documentacion de API debe reflejar si el dato es global o tenant
  • toda API de datos debe heredar la semantica de tenant_id
  • la sensibilidad del dato documentado debe alinearse con el dominio fuente
  • ejemplos y responses no deben romper el aislamiento definido en la Data Foundation

Documento rector relacionado:

Relacion con tenants

La plataforma de documentacion debe respetar desde el inicio la Multi-Tenant Foundation.

Reglas:

  • debe distinguir APIs globales de APIs por tenant
  • debe permitir documentar APIs especificas de alpuntodeventa
  • debe permitir documentar APIs especificas de ladirecta
  • debe permitir documentar APIs internas y externas sin mezclar ownership
  • nunca debe presentar como equivalente una API de un tenant con la de otro si su contrato, permisos o datos cambian

Documento rector relacionado:

Que no implementa todavia

Esta etapa no implementa todavia:

  • instalacion real de Swagger UI
  • APIs propias reales
  • tokens reales
  • secretos reales
  • endpoints productivos o internos expuestos
  • auditoria runtime real

Herramienta recomendada

Estado runtime actual

Al 2026-06-02 ya existe un PostgREST sandbox interno no publico que entrega OpenAPI inicial dentro de la red Docker privada desde un runtime unico protegido con JWT sandbox:

  • openclaw-postgrest-sandbox:3000

La etapa 15.5 agrego refinamiento del contrato runtime con metadata SQL humana y reglas de exportacion segura en docs/governance/operations/OPENAPI-REFINEMENT-SANDBOX.md.

La etapa 15.6 ya publica Scalar sobre contratos sanitizados en:

  • https://developers.alpuntodeventa.com.ar

Modelo aplicado:

  • PostgREST sigue interno
  • Scalar monta solo JSON sanitizados desde Git
  • el boton de prueba real queda oculto
  • el host visible del contrato apunta a /mock

Opcion principal recomendada

  • Scalar

Alternativa aceptable

  • Swagger UI

Justificacion de la recomendacion

Soporte OpenAPI

Scalar se adapta bien al objetivo porque parte naturalmente de contratos OpenAPI, que ya son obligatorios en la API Platform.

Interfaz moderna

Scalar ofrece una experiencia visual mas moderna y clara para leer endpoints, ejemplos, esquemas y autenticacion.

Posibilidad de probar APIs

La herramienta soporta exploracion y pruebas interactivas desde navegador, lo que encaja con el objetivo futuro de tener un playground controlado.

Buena experiencia para desarrolladores

La lectura de requests, responses, errores y modelos resulta mas simple para equipos internos, terceros y futuros agentes consumidores.

Integracion futura con Git y portal

Scalar encaja bien con el modelo del proyecto porque puede vivir como capa documental gobernada desde Git y publicarse dentro del portal oficial de documentacion o como subportal dedicado.

Arquitectura objetivo

flowchart TD
    pg[PostgreSQL]
    runtime[PostgREST / APIs propias]
    openapi[OpenAPI]
    scalar[Scalar]
    portal[API Documentation Portal]

    pg --> runtime
    runtime --> openapi
    openapi --> scalar
    scalar --> portal

Lectura:

  • PostgreSQL sigue siendo la tecnologia objetivo de datos
  • PostgREST / APIs propias representan la futura capa runtime
  • OpenAPI es el contrato obligatorio entre runtime y documentacion
  • Scalar es la herramienta recomendada para visualizar y probar
  • el API Documentation Portal es la experiencia final navegable

Estructura futura

La estructura futura recomendada para el portal de APIs es:

  • APIs Globales
  • APIs por Tenant
  • Alpuntodeventa APIs
  • La Directa APIs
  • APIs internas
  • APIs externas

Lectura recomendada de la estructura

  • APIs Globales: metadata, health, catalogos o capacidades compartidas
  • APIs por Tenant: capa contenedora para APIs con tenant_id
  • Alpuntodeventa APIs: endpoints y contratos propios de ese tenant
  • La Directa APIs: endpoints y contratos propios de ese tenant
  • APIs internas: consumo para plataforma, automatizaciones y agentes
  • APIs externas: consumo para clientes, apps o terceros autorizados

Contrato obligatorio de documentacion

Toda API documentada debe incluir como minimo:

  • OpenAPI
  • descripcion simple
  • tenant_id o scope=global
  • owner
  • metodo
  • endpoint
  • parametros
  • ejemplo de request
  • ejemplo de response
  • permisos requeridos
  • scopes
  • sensibilidad del dato
  • estado: futuro, sandbox o productivo

Reglas obligatorias

  • ninguna API se considera lista para portal sin OpenAPI
  • ningun ejemplo puede contener secretos reales
  • toda API de tenant debe declarar explicitamente tenant_id o su modelo de aislamiento
  • toda API debe tener owner claro
  • todo endpoint debe indicar si su consumo esperado es interno, externo o ambos
  • toda documentacion debe distinguir entre realidad implementada y roadmap futuro

Reglas para pruebas desde interfaz

Las pruebas interactivas futuras deben cumplir:

  • usar solo tokens controlados
  • nunca mostrar secretos reales en pantalla
  • usar datos de prueba cuando corresponda
  • separar estrictamente sandbox de productivo
  • dejar preparada auditoria futura de requests de prueba

Modelo de entornos para pruebas

  • futuro: API documentada pero no disponible para ejecutar
  • sandbox: API disponible solo con datos y tokens controlados
  • productivo: API publicada bajo permisos, auth y auditoria aprobados

URLs futuras evaluadas

Opciones analizadas:

  • api-docs.alpuntodeventa.com.ar
  • developers.alpuntodeventa.com.ar

Evaluacion

api-docs.alpuntodeventa.com.ar

Ventajas:

  • deja clara la especializacion del subportal
  • escala mejor si el volumen de APIs crece

Riesgos:

  • agrega otra publicacion y otra identidad de entrypoint

developers.alpuntodeventa.com.ar

Ventajas:

  • sirve a largo plazo para un portal mas amplio de terceros y partners
  • ya existe y queda alineado con un portal de developers real

Riesgos:

  • no debe usarse en 15.4
  • no debe publicarse antes de cerrar 15.6

Recomendacion inicial

La recomendacion aprobada es:

  • reservar developers.alpuntodeventa.com.ar para 15.6

Motivo:

  • ya existe como DNS futuro decidido para Scalar y la API Documentation Platform
  • evita mezclar la etapa 15.4 con una publicacion anticipada
  • permite mantener el sandbox completamente interno hasta que exista documentacion interactiva real

Casos de uso

Caso 1 - Desarrollador consulta documentacion de clientes

Un desarrollador revisa la documentacion de clientes, entiende metodo, parametros, permisos, ejemplo de request y ejemplo de response antes de tocar ninguna integracion.

Caso 2 - Usuario interno prueba API de ventas de La Directa

Un usuario interno autorizado entra al portal, selecciona la API de ventas de ladirecta y realiza una prueba solo en entorno sandbox con token controlado.

Caso 3 - Tercero autorizado consulta stock

Un integrador externo revisa el contrato de stock, aprende scopes y errores esperados, y ejecuta una prueba controlada sin ver secretos reales.

Caso 4 - Agente OpenClaw consume endpoint interno

Un agente o workflow interno usa la documentacion para conocer el contrato de un endpoint interno y su alcance exacto antes de consumirlo.

Caso 5 - Token invalido debe fallar

Si una prueba se realiza con token invalido, sin scope suficiente o contra el tenant incorrecto, la interfaz debe mostrar rechazo esperado y nunca devolver datos sensibles.

Diagramas Mermaid

API documentation flow

flowchart LR
    author[Equipo / owner API] --> contract[Contrato OpenAPI]
    contract --> review[Revision de seguridad y alcance]
    review --> scalar[Scalar]
    scalar --> portal[Portal de documentacion]
    portal --> users[Internos / terceros / agentes]

OpenAPI generation flow

flowchart LR
    data[Data Foundation]
    api[API Platform]
    contract[OpenAPI]
    docs[API Documentation Platform]

    data --> api
    api --> contract
    contract --> docs

Tenant-safe test flow

flowchart TD
    user[Usuario autorizado] --> token[Token controlado]
    token --> scope[Scopes y tenant_id]
    scope --> sandbox[Sandbox]
    sandbox --> audit[Auditoria futura]
    audit --> response[Response filtrada]

Sandbox vs production flow

flowchart LR
    docs[Portal API Docs] --> future[Futuro<br/>solo lectura]
    docs --> sandbox[Sandbox<br/>pruebas controladas]
    docs --> prod[Productivo<br/>auth y permisos reales]

Roadmap interno

Las siguientes subetapas quedan definidas solo como roadmap interno:

  • 16.1 API Documentation Contract
  • 16.2 OpenAPI examples
  • 16.3 Scalar sandbox
  • 16.4 API Docs portal
  • 16.5 Test tokens
  • 16.6 Publicacion controlada
  • 16.7 Integracion con Knowledge Portal

Decisiones ya tomadas

  • la API Documentation Platform queda aprobada como capa documental oficial
  • Scalar queda recomendado como opcion principal
  • Swagger UI queda aceptado como alternativa
  • toda API futura debe publicarse con contrato OpenAPI
  • el DNS sandbox publicado es developers.alpuntodeventa.com.ar
  • no debe apuntar nunca al runtime interno real de PostgREST
  • las pruebas interactivas futuras deben nacer separando sandbox de productivo

Decisiones pendientes

  • si el primer portal visible sera ruta dentro de doc.* o subdominio propio
  • como se generara el OpenAPI real desde PostgREST o APIs propias
  • politica final de tokens de prueba
  • politica final de auditoria de pruebas interactivas
  • estrategia final de publicacion para terceros externos

Regla final

Ninguna documentacion futura de API se considera aprobada si no respeta al mismo tiempo:

Y por encima de todo:

  • ninguna experiencia de documentacion o prueba puede debilitar el aislamiento entre tenants