pronto-rest 0.0.1

Shared API response envelope for FastAPI projects

pronto-rest

Shared API utilities for FastAPI projects.

What's included

pronto_rest.v1 — stable public API:

• ApiResponse[T] — generic response envelope that every endpoint returns. Carries either a typed data payload (on success) or an ApiError (on failure), never both.
• ApiError — structured error model with a machine-readable code, a human-readable message, and an optional details dict.
• EmptyData — use as the data type when an operation succeeds but returns no domain payload.

Installation

pip install pronto-rest

Or, for local development with editable install:

pip install -e ".[dev]"

Usage

from pronto_rest.v1 import ApiResponse, ApiError

# Success response
response = ApiResponse.ok(
    data={"id": "123", "name": "Alice"},
    operation="create_user",
    endpoint="/api/v1/users/create",
)

# Error response
response = ApiResponse.fail(
    code="USER_NOT_FOUND",
    message="No user with that ID exists.",
    operation="get_user",
    endpoint="/api/v1/users/123",
    details={"user_id": "123"},
)

With FastAPI

from fastapi import APIRouter
from pronto_rest.v1 import ApiResponse, EmptyData

router = APIRouter()

@router.post("/users/create", response_model=ApiResponse[UserOut])
def create_user(body: UserIn) -> ApiResponse[UserOut]:
    user = db.create(body)
    return ApiResponse.ok(
        data=UserOut.model_validate(user),
        operation="create_user",
        endpoint="/api/v1/users/create",
    )

Response envelope shape

Every response shares this envelope:

Field	Type	Description
api_version	str	Always "1.0"
status	"success" | "error"	Outcome of the operation
correlation_id	str (UUID)	Trace ID; echoed from X-Correlation-ID header if present
timestamp	datetime	UTC timestamp of when the response was generated
operation	str	Logical operation name (e.g. create_user)
endpoint	str	Request path (e.g. /api/v1/users/create)
data	T | null	Response payload; null on error
error	ApiError | null	Error details; null on success

status="success" requires data and forbids error. status="error" requires error and forbids data.

Development

Run tests:

pytest

Versioning

Versions are derived from git tags via hatch-vcs. The file src/pronto_rest/_version.py is auto-generated at build time and is not tracked in version control — the git tag is the source of truth.

To release a new version, tag a commit and build:

git tag v0.2.0
hatch build