Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Compatibilidad HTTP y OpenAPI

Estado: Activo Alcance: estado actual Última revisión: 2026-09-02 Responsable: SDK de ax-code

AX Code tiene dos vías de integración:

El nombre de paquete JSR de abajo está listo para publicarse, pero aún no ha recibido su primera versión pública.

• Usa @defai-digital/ax-code-sdk para la integración de aplicaciones de primera parte en TypeScript y JavaScript.
• Usa @defai-digital/ax-code-sdk/headless o @defai-digital/ax-code-sdk/grpc para el trabajo de aplicaciones de primera parte y de interfaz de escritorio.
• Usa ax-code serve más el contrato OpenAPI cuando hace falta otro lenguaje o un límite de proceso de compatibilidad.
• Usa transporte nativo del SDK para el trabajo de interfaz de escritorio de primera parte en el que AX Code es dueño de ambos extremos del transporte.

La vía HTTP/OpenAPI es infraestructura de compatibilidad y de clientes generados. Permite que Python, Go, Java, Rust y otros clientes llamen a la misma API del servidor sin que AX Code se comprometa a mantener un paquete oficial completo para cada lenguaje. No debe tratarse como el puente privilegiado preferido dentro de una interfaz de escritorio de primera parte cuando el contrato gRPC/nativo está disponible, y ya no se expone como subcaminos del SDK de JavaScript de primera parte.

Elegir una vía

Qué es oficial hoy

• @defai-digital/ax-code-sdk es el SDK de primera parte de TypeScript y JavaScript; sus límites públicos de aplicación son headless y grpc.
• @defai-digital/ax-code-sdk/grpc es la fachada opcional de primera parte del transporte headless de escritorio y nativo.
• @defai-digital/ax-code-sdk/headless es el SDK de primera parte de ciclo de vida y eventos de TypeScript y JavaScript para límites de proceso de backend local.
• packages/sdk/openapi.json es la instantánea OpenAPI para clientes HTTP generados.
• Los clientes generados que no son de JavaScript se admiten como integraciones sobre HTTP, pero no son paquetes publicados de primera parte salvo que existan un responsable del paquete, pruebas y un flujo de versión.

Flujo HTTP básico

Inicia el servidor:

export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096

La ayuda de ciclo de vida @defai-digital/ax-code-sdk/headless genera una contraseña de Basic Auth de un solo uso y conecta el cliente devuelto con la cabecera Authorization correspondiente de forma automática. Quienes usen ax-code serve a mano deben establecer AX_CODE_SERVER_PASSWORD de forma explícita y enviar la cabecera Basic Auth correspondiente. La documentación OpenAPI en vivo en /doc y todos los endpoints del servidor son solo loopback.

Las ayudas de backend gestionadas por el SDK rechazan siempre nombres de host de red como 0.0.0.0. La opción heredada allowNetworkBind se conserva por compatibilidad del código fuente, pero ya no elude la política de solo local. Los shells de interfaz de escritorio deben preferir @defai-digital/ax-code-sdk/grpc o un límite de SDK en proceso.

Las ayudas HTTP del entorno de ejecución ya no son subcaminos públicos del SDK de JavaScript. El paquete sigue conteniendo internos del cliente generado porque @defai-digital/ax-code-sdk/headless, el respaldo HTTP de gRPC y el código heredado del entorno de ejecución de AX Code los usan, pero las integraciones externas deben usar headless, gRPC o clientes generados desde la instantánea OpenAPI en lugar de importar valores HTTP del entorno de ejecución desde @defai-digital/ax-code-sdk.

Comprueba la salud del servidor:

curl http://127.0.0.1:4096/global/health

Crea clientes generados desde la instantánea OpenAPI después de validar la instantánea como JSON y OpenAPI:

openapi-python-client generate --path packages/sdk/openapi.json

oapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.go

openapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-java

Protecciones de la generación

Trata el documento OpenAPI como el contrato neutro respecto al lenguaje. No mantengas a mano envoltorios grandes alrededor de rutas individuales salvo que haga falta una capa ergonómica pequeña.

Fija juntas la versión de AX Code y la versión del cliente generado. Si cambia el esquema de rutas del servidor, regenera el cliente y publícalo con una nota clara de compatibilidad.

Mantén el código generado aparte de las ayudas escritas a mano. Los archivos generados deben ser fáciles de sustituir, mientras que los archivos escritos a mano deben contener solo autenticación, valores predeterminados, reintentos y API de conveniencia de nivel superior.

Conserva el comportamiento del límite de servicio. Los clientes que no son de JavaScript usan la vía del servidor HTTP y no obtienen createAgent() en proceso, ejecución de herramientas personalizadas de JavaScript ni utilidades @defai-digital/ax-code-sdk/testing.

Cubre las partes difíciles antes de promover un cliente generado a estado de primera parte:

1. La validación OpenAPI se ejecuta en CI.
2. Una prueba de contrato inicia ax-code serve y llama a rutas representativas.
3. El comportamiento de flujo o SSE se prueba si el cliente expone API de eventos.
4. Las cabeceras de ámbito de directorio y el comportamiento de autenticación están documentados.
5. La publicación, el versionado y la responsabilidad son explícitos.

El paquete del SDK incluye una protección local ligera para la instantánea actual:

pnpm run check:openapi

El comando a nivel de paquete también está disponible al trabajar dentro del paquete del SDK:

pnpm --dir packages/sdk/js run validate:openapi

Esto valida que packages/sdk/openapi.json sea JSON analizable, declare OpenAPI 3.x y contenga las rutas centrales que necesitan los clientes generados.