Validate and preview projects

Check the linking contract statically, emit machine-readable results, or run a local development server.

Installation#

Install only the compiler and runtime engine:

python -m pip install "apizit-linking==1.0.1"

Include the FastAPI adapter and Uvicorn local server for preview:

python -m pip install "apizit-linking[preview,models]==1.0.1"

The validate command#

Synopsis

apizit-linking validate [TARGET] [--project-root DIRECTORY] [--json]

TARGET defaults to the current directory. It may be a project directory or a specific apizit_linking.yaml, .yml, or .json file.

Examples#

# Discover a manifest in the current directory
apizit-linking validate .

# Validate an independent example directory
apizit-linking validate examples/task-api

# Resolve a specific manifest against an explicit project root
apizit-linking validate config/apizit_linking.yaml --project-root .

# Emit JSON for CI or another tool
apizit-linking validate . --json

JSON result#

JSON mode includes the resolved file and project root, manifest version, compiled runtime routes, and aggregated diagnostics:

{
  "valid": true,
  "file": "/project/apizit_linking.yaml",
  "project_root": "/project",
  "version": 1,
  "routes": [
    {
      "index": 0,
      "path": "/hello",
      "method": "GET",
      "function": "hello:hello",
      "module": "hello",
      "function_name": "hello",
      "parameters": {}
    }
  ],
  "diagnostics": []
}

Validation exits with status 0 when the definition is valid and 1 when blocking diagnostics are present.

The preview command#

Synopsis

apizit-linking preview [TARGET]
  [--project-root DIRECTORY]
  [--host HOST]
  [--port PORT]
  [--allow-network]

Preview validates first, then imports the customer modules and serves the compiled routes through the optional FastAPI adapter.

Examples#

# Local loopback preview
apizit-linking preview . --port 8080

# Preview one project in the gallery
apizit-linking preview examples/json-body --port 8080

# Deliberately expose the development server on the local network
apizit-linking preview . --host 0.0.0.0 --port 8080 --allow-network

Network safety: preview refuses a non-loopback --host unless --allow-network is also present. That flag only acknowledges exposure; it does not add authentication, encryption, sandboxing, or production hardening.

Exit behavior#

Use in CI#

Pin the beta version, validate each independent project, and let the non-zero exit status fail the job:

python -m pip install "apizit-linking==1.0.1"
apizit-linking validate .

for manifest in examples/*/apizit_linking.yaml; do
  apizit-linking validate "$(dirname "$manifest")"
done

• Read the manifest contract
• Run validate and preview end to end
• Understand preview and runtime boundaries

Inspect and locate routes#

apizit-linking routes [TARGET] [--project-root DIRECTORY] [--json]
apizit-linking explain [TARGET] --method GET --path /tasks/12 [--json]

These commands compile statically. routes returns the effective map, source/manifest paths, one-based function lines, stable route IDs and file fingerprints. explain accepts a concrete path or URL, strips its query and returns the selected entry; no match exits 1. JSON events use the same route ID and Python source fingerprint.

Export and compare contracts#

apizit-linking export [TARGET] --format contract --output before.json
apizit-linking export [TARGET] --format runtime --output runtime.json
apizit-linking export [TARGET] --resolve-models --output resolved.json
apizit-linking export [TARGET] --format openapi --resolve-models --output openapi.json
apizit-linking diff before.json after.json --json

contract is the default export format. runtime creates a closed engine-bound artifact. Static exports do not import code. --resolve-models explicitly executes imports and the runtime factory to prepare OpenAPI with the same typed adapters as requests; openapi export requires that flag. Use controlled data and credentials. --output writes a UTF-8 JSON file; otherwise JSON goes to stdout.

diff exits 0 for a compatible HTTP contract, 1 for changed/removed contracts, and 2 for invalid exports or unresolved typed changes. It conservatively compares signatures, bindings, statuses, errors, security and prepared schemas. Additive schema changes can require review too. A matching contract cannot prove business correctness; run the application tests.

Development reload#

preview accepts --reload. It watches project Python/YAML/JSON, statically validates changes and starts a fresh worker for valid changes. Static errors retain the prior worker; runtime preparation failures can interrupt availability. The supervisor targets its own worker process tree on Windows, and does not guarantee lifespan cleanup during forced restart. Preview remains a local development tool.