Client

openapi_first.client

OpenAPI-first HTTP client for contract-driven services.

Summary

This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.

It is the client counterpart to OpenAPIFirstApp.

Notes

Core Principles:

- The OpenAPI specification is the single source of truth
- Each operationId becomes a callable Python method
- No implicit schema mutation or inference
- No code generation step
- Minimal abstraction over httpx

Responsibilities:

- Parses an OpenAPI 3.x specification
- Dynamically creates one callable per operationId
- Enforces presence of servers, paths, and operationId
- Formats path parameters safely
- Handles JSON request bodies explicitly
- Returns raw `httpx.Response` objects

Constraints:

- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.

Classes

OpenAPIClient

OpenAPIClient(spec: Dict[str, Any], base_url: Optional[str] = None, client: Optional[httpx.Client] = None)

OpenAPI-first HTTP client (httpx-based).

Notes

Responsibilities:

- This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.

Guarantees:

- One callable per operationId
- Explicit parameters (path, query, headers, body)
- No implicit schema inference or mutation
- Returns raw `httpx.Response` objects
- No response validation or deserialization

Example

from openapi_first import loader, client

spec = loader.load_openapi("openapi.yaml")

api = client.OpenAPIClient(
    spec=spec,
    base_url="http://localhost:8000",
)

# Call operationId: getUser
response = api.getUser(
    path_params={"user_id": 123}
)

print(response.status_code)
print(response.json())

Initialize the OpenAPI client.

Parameters:

Name	Type	Description	Default
`spec`	`dict[str, Any]`	Parsed OpenAPI 3.x specification.	required
`base_url`	`str`	Base URL of the target service. If omitted, the first entry in the OpenAPI `servers` list is used.	`None`
`client`	`Client`	Optional preconfigured httpx client instance.	`None`

Raises:

Type	Description
`OpenAPIClientError`	If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.

Functions

OpenAPIClientError

Bases: OpenAPIFirstError

Raised when an OpenAPI client operation fails.