byaml-schema-api — BYaML Schema Registry API v2 (ByaML-003)

Servicio público schema.byaml.org (v2) que sirve el Architecture Graph v0.4 de BYaML: schema (JSON Schema), catalog, policies y relationships, versionado desde un registry S3.

Endpoints

Método	Ruta	Descripción
GET	/v1/graph/schema/version/latest	{"latest": "0.4.0"}
GET	/v1/graph/schema/version/{v}/schema	JSON Schema del grafo v0.4
GET	/v1/graph/schema/version/{v}/catalog	Tipos del catálogo (≥17 baseline)
GET	/v1/graph/schema/version/{v}/policies	Policy rules
GET	/v1/graph/schema/version/{v}/relationships	Relationship matrix
GET	/v1/graph/health	200 si el servicio está OK

• Versionado: manifest.json en S3 define latest + versions. Soporta 0.4.x.
• Cache: lectura de S3 con cache 5 min.
• Fallback: si S3 no está disponible, sirve desde schema/<version>/ local (modo dev/offline).

Run (local)

uv sync --extra dev
AWS_PROFILE=cc AWS_REGION=us-east-1 uvicorn main:app ... # ver src/byaml_schema_api/main.py

Para modo local sin S3 (fallback): set BYAML_REGISTRY_FALLBACK_DIR a la carpeta del schema.

Docs OpenAPI

Se sirven automáticamente en /docs (Swagger) y /openapi.json (FastAPI).

Stack

• Python FastAPI (core) + boto3 (S3).
• Go wrapper (binario) — mismo contrato HTTP (rama feat/api-go).
• Lambda handler (src/byaml_schema_api/lambda_handler.py) — handler nativo para AWS Lambda (API Gateway REST AWS_PROXY), envuelve registry.py de la v2. Es lo que corre en producción en https://schema.byaml.org.

Deploy (producción — AWS Lambda + API Gateway)

Estado real (2026-08-21): la v2 está deployada y pública en https://schema.byaml.org/v1/graph/....

# 1) publicar schema a S3 (desde byaml-spec)
~/dev/breakingthecloud/byaml-next/byaml-spec/scripts/publish.sh 0.4.0

# 2) empaquetar lambda (código + pyyaml cp311)
uv pip install --target /tmp/build --python-version 3.11 --python-platform x86_64-manylinux2014 PyYAML
cp -r src/byaml_schema_api /tmp/build/ && cd /tmp/build && zip -qr /tmp/v2.zip .

# 3) actualizar lambda + handler
aws lambda update-function-code --function-name byaml-schema-api-api --zip-file fileb:///tmp/v2.zip --region us-east-1
aws lambda update-function-configuration --function-name byaml-schema-api-api --handler byaml_schema_api.lambda_handler.handler --region us-east-1

# 4) primer deploy solo: crear+asignar deployment del API Gateway (si integración quedó vieja)
#   aws apigateway create-deployment ... && aws apigateway update-stage ...

Acceso: header x-api-key (usage plan byaml-schema-api-usage-plan, quota 100/día).

• API key v2: byaml-schema-api-key-v2 (id 2t5u9mz21j).
• Verify: curl -H "x-api-key: $KEY" https://schema.byaml.org/v1/graph/health.