apizit-linking

apizit-linking is a standalone declarative Python-to-HTTP binding engine. It turns a versioned configuration file into validated HTTP routes while keeping customer Python code unchanged. APIZIT is one platform that consumes it, not a dependency of the package.

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

There are no APIZIT decorators, imports, handlers, or web routes in customer code.

Install the public beta

The core validation and runtime engine requires only PyYAML:

pip install "apizit-linking==0.3.0"

Install the local FastAPI preview as an optional extra:

pip install "apizit-linking[preview]==0.3.0"
apizit-linking validate .
apizit-linking preview . --port 8080

Version 0.3.0 is a public beta. Pin the exact version in projects and deployment artifacts until the compatibility policy is declared stable.

Validate locally

The command searches the target directory for apizit_linking.yaml, apizit_linking.yml, then apizit_linking.json:

apizit-linking validate .
apizit-linking validate . --json
apizit-linking validate path/to/apizit_linking.yaml --project-root .

Validation is static. It parses the customer module with the Python AST and does not import or execute customer code.

Preview locally

apizit-linking preview . --port 8080

Preview binds to 127.0.0.1 by default. It validates before importing customer modules, then executes them in the server process. Binding to a non-loopback interface requires --allow-network.

The preview server is a development tool, not an authentication layer, a production deployment boundary, or a sandbox. Linked customer modules are ordinary trusted Python code and may execute arbitrary code when imported or called.

V1 configuration reference

The root document is a closed, versioned object:

version: 1
runtime:
  language: python
  version: "3.12"
routes:
  - path: /customers/{customer_id}
    method: PATCH
    function: customer_service:update_customer

function uses the canonical dotted module:function form. path must be an absolute HTTP path and route placeholders use {parameter_name}. Methods are normalized to uppercase and must be one of GET, POST, PUT, PATCH, DELETE, OPTIONS, or HEAD.

The compiler verifies module and function existence, top-level callability, supported signatures, parameter bindings, request-source compatibility, and route collisions. A static sibling such as /customers/search is registered before /customers/{customer_id} regardless of declaration order. Cross-shaped patterns that overlap without a safe specificity order are rejected as ROUTE_AMBIGUITY.

Explicit parameter sources

The canonical source syntax is a structured object:

parameters:
  customer_name:
    source:
      location: body
      name: name

This binds HTTP body field name to Python parameter customer_name. When a source is explicit, only that source is inspected. There is no fallback to another source.

V1 supports:

• path
• query
• header
• body
• form
• file

Header names are case-insensitive; other external names are exact. A route cannot require both a JSON body value and a form or file value because those request encodings are incompatible.

Automatic parameter resolution

If a parameter has no explicit source, V1 searches its Python name in this stable order:

path > query > header > body > form > file

The first present source wins. A required absent parameter produces PARAMETER_NOT_FOUND; explicit mode produces PARAMETER_NOT_FOUND_IN_SOURCE. Parameters with Python defaults are omitted from the generated keyword arguments so Python applies their defaults.

Missing values, JSON null, and empty strings are distinct. null is accepted only by a nullable annotation. V1 converts primitive str, int, float, bool, nullable unions, lists, and dictionaries. If one annotation contains an unknown forward reference, other resolvable annotations are still converted.

Stable error shape

Request errors use a JSON object:

{
  "error": {
    "code": "PARAMETER_NOT_FOUND_IN_SOURCE",
    "message": "Required field 'name' was not found in request source 'body'.",
    "parameter": "customer_name",
    "external_name": "name",
    "source": "body"
  }
}

Configuration diagnostics include a stable code, severity, field, route index, parameter, and relevant source metadata. The beta does not yet guarantee that new minor releases will never add diagnostic codes or metadata fields.

Python API

Platform adapters compile with compile_linking_file, serialize each validated RouteDefinition, then use RequestContext, resolve_arguments, load_functions, and invoke_function in the customer runtime. Compilation is the static boundary; customer imports happen only through the runtime loader.

The optional ASGI adapter is available without changing customer code:

from apizit_linking.fastapi import create_app

app = create_app(".")

Platforms may wrap that app with their own server, authentication, metering, or deployment layer. FastAPI documentation routes are disabled by default because V1 does not yet generate a complete request/response OpenAPI contract; pass docs=True only when that limitation is acceptable.

Package scope

The package owns discovery, YAML/YML/JSON parsing, closed V1 validation, safe static module:function resolution, AST signature inspection, compilation, structured diagnostics, request-context resolution, primitive conversion, sync/async invocation, and the optional FastAPI preview.

It intentionally does not own Mangum, API Gateway, Lambda, deployment, metering, or APIZIT scan UI/reporting. The core installation remains independent of FastAPI.

Development

git clone https://github.com/chipsi44/apizit-linking.git
cd apizit-linking
uv sync --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

The complete V1 reference, release procedure, remaining work, examples, and tests are included in the source distribution. APIZIT Linking is licensed under Apache-2.0.