APIZIT Linking

Python APIs with clear context for AI. Keep the code. Add the API. Write and test ordinary Python functions, define the HTTP contract separately, and follow a route straight back to its source.

Linking is a standalone declarative JSON API framework. Its core requires PyYAML; FastAPI serving and Pydantic models are optional extras. It needs no APIZIT account.

Documentation · Quickstart · Fork the examples · Issues

# customer_service.py — existing business code stays unchanged
def create_customer(customer_name: str, age: int):
    return {"name": customer_name, "age": age}

version: 1
routes:
  - path: /customers
    method: POST
    function: customer_service:create_customer
    parameters:
      customer_name:
        source: {location: body, name: name}
      age:
        source: {location: body, name: age}
    response: {status: 201}

Evaluate Linking 1.0

The registry-verified evaluation package is 1.0.0rc1. This branch prepares 1.0.1rc1, correcting inline Annotated field comparison before stable publication. The reserved v1.0.0 tag did not publish files; it remains immutable. Consult the public release record for the next verified package.

Python 3.10–3.14, Apache-2.0. Pin the exact package for a reproducible deployment. PyPI is the authority for published versions. The 1.0 contract follows Semantic Versioning; production readiness of an application also depends on its hosting, identity, storage and operational controls.

python -m pip install "apizit-linking[preview,models]==1.0.0rc1"
apizit-linking validate . --json
apizit-linking preview . --port 8080

For static tooling alone, install apizit-linking==1.0.0rc1. Validation parses the manifest and Python AST without importing customer code. Preview imports trusted code, binds to loopback by default and requires --allow-network for other hosts. It is a development server; serve with ASGI for an application-owned deployment.

Three reasons to choose Linking

• Two clear tasks. Review Python behavior and its direct tests first, then review HTTP wiring. Existing libraries stay usable from scripts and jobs.
• One route map. Method and pattern lead to module:function, source file and line. JSON request events carry route IDs and a source fingerprint for diagnosis.
• A checkable contract. Static diagnostics, editor schema, typed OpenAPI and conservative contract comparison provide gates for proposed changes.

These properties help people and coding assistants find and review the relevant context. They establish no universal improvement in token use, speed or reliability. Flask blueprints and FastAPI routers/service layers can also separate business code. Choose Linking for its external manifest and inspection workflow; choose a native framework when its Python HTTP interface or broader ecosystem fits better.

Build a persistent, protected API

Opt into validation: typed to prepare Pydantic input and output adapters, nested models and their schemas. Body bindings accept RFC 6901 pointers. Omitted typed mode retains legacy conversion; legacy return schemas remain documentary.

A separate runtime.factory registers named resource providers and guards. Providers inject database connections and principals into ordinary functions; request/application contexts manage acquisition and cleanup. Guards run in order, fail closed and leave identity and owner policy to the application. Declarative response and errors supply success status/headers and safe domain-error mappings. 204/205/HEAD omit bodies; unmapped errors return a generic JSON 500.

The standalone SQLite example demonstrates nested models, transactions, owner permissions, process-restart persistence and 201/204/400/401/403/404/409 without APIZIT. Applications own their database, identity service, secrets, migrations and backups.

Locate and control a change

apizit-linking routes . --json
apizit-linking explain . --method GET --path /tasks/12 --json
apizit-linking export . --resolve-models --output before.json
# Edit the business code, then run its direct and HTTP tests.
apizit-linking validate . --json
apizit-linking export . --resolve-models --output after.json
apizit-linking diff before.json after.json --json

--resolve-models explicitly imports project code and prepares its runtime factory. Static exports do not. Diff exits 0 for compatibility, 1 for changed/removed contracts and 2 for invalid exports or unresolved typed changes. Compatible HTTP does not prove business correctness. See the diagnostic workflow.

Integration and limits

from apizit_linking.fastapi import create_app
app = create_app(".")

The ASGI factories keep documentation disabled unless docs=True. Platforms can compile with compile_linking_file, serialize CompilationResult.to_runtime_dict() and load via create_app_from_runtime_artifact. Manifest schema v1 remains stable; 1.0 artifacts use format v2 and require the exact compiling engine version. Recompile after every engine change; never vendor the engine into an adapter.

Opt-in RequestLimits bounds received body, query pairs, JSON structure and active requests. Optional asynchronous business deadlines return 504 after cleanup. Synchronous work cannot be forcibly stopped; external servers own connection, header and process limits. Typed routes require HTTP-parameter and return annotations; explicit Any supplies no filtering. Models and mutable instances follow Pydantic's configuration and instance-revalidation policy. Legacy return schemas remain documentary.

There is no portable streaming/WebSocket contract, built-in ORM, identity provider, deployment service or execution sandbox. Private import namespaces prevent module collisions. Read current limits and migration. APIZIT is a separate optional hosting platform.

Development and documentation

uv sync --locked --all-extras --all-groups
uv run python -m unittest discover -s tests -p "test_*.py"
uv run ruff check src tests
uv run black --check src tests
uv build --clear --build-constraints build-constraints.txt --require-hashes

CI checks source, real HTTP/restart/reload, minimum dependencies, core-only installation, wheel installation on Linux/Windows/macOS and identical double builds. Maintainer contracts and qualification evidence are in docs/. English public documentation is edited once in the examples repository and exported with source commit and hashes to APIZIT /linking/. GitHub Pages stays public during the protected-site transition; /docs/linking/ remains the SaaS guide.