Skip to content

# Client

## `` openapi_first.client

### Summary

OpenAPI-first HTTP client for contract-driven services.

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:

    1
    2
    3
    4
    5

    - 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:

    1
    2
    3
    4
    5
    6

    - 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:

    1

    - 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

    1

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

OpenAPI-first HTTP client (`httpx`-based).

Notes

Responsibilities:

    1
    2
    3

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

Guarantees:

    1
    2
    3
    4
    5

    - 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

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16

    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.