autoendpoint 0.3.0

Library to create basics endpoints from Models SQLModels

Auto Endpoint

autoendpoint is a lightweight library for FastAPI that automatically generates asynchronous RESTful API endpoints for your SQLModel classes. It simplifies the creation of CRUD operations by dynamically building Pydantic models for data validation and handling database interactions using SQLAlchemy's AsyncSession.

Key Features

• Full CRUD Endpoints: Automatically generates GET (all), POST (create), GET (by ID), PUT (update), PATCH (partial update), DELETE, GET (by unique field), and GET (by any field filter) endpoints for any SQLModel.
• Dynamic GraphQL Endpoint: Automatically generates a GraphQL schema and adds a /graphql endpoint (powered by Strawberry) to query your models.
• Automatic Relationship Discovery: Automatically identifies and maps SQLModel relationships into the GraphQL schema, enabling seamless nested queries (e.g., fetching a Profile or Posts through a UserAccount) with automatic pre-loading to prevent MissingGreenlet errors.
• String Representation in GraphQL: Automatically includes a string_representation field in GraphQL queries, which uses your model's __str__ method for flexible object display.
• Enhanced OpenAPI Documentation: All generated endpoint parameters (Body, Path, Query) include clear, dynamic descriptions for better readability in tools like FastMCP and Swagger UI.
• Asynchronous Support: Built for high-performance async workflows using AsyncSession.
• Smart Model Generation: Dynamically creates schemas for creation, full updates, and partial updates (PATCH), excluding primary keys from request bodies.
• Flexible Retrieval:
  • Unique Retrieval: Endpoint to fetch a single record by any unique field (e.g., email), with error handling for duplicates.
  • Generic Filtering: New endpoint to retrieve multiple records by any field and value.
• FastAPI Integration: Seamlessly integrates with existing FastAPI applications using an APIRouter.
• Type Safety: Leverages Python type hints and SQLModel/Pydantic for robust validation.
• Google Style Docstrings: Fully documented for Sphinx compatibility.

Installation

You can install autoendpoint using uv. To include asynchronous database support (e.g., PostgreSQL), use the postgresql extra:

# Basic installation
uv add autoendpoint

# Installation with PostgreSQL support (asyncpg, greenlet, psycopg2-binary)
uv add "autoendpoint[postgresql]"

Note: The library is designed to be driver-agnostic but requires greenlet and a compatible async driver (like asyncpg or aiosqlite) for SQLAlchemy's asynchronous operations.

Quick Start

Here's how to use AutoEndpoint in your FastAPI project:

1. Define your SQLModel

import uuid
from sqlmodel import Field, SQLModel
from typing import Optional

class Hero(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    name: str
    secret_name: str
    age: Optional[int] = None
    email: str = Field(unique=True)

    def __str__(self):
        return f"{self.name} ({self.age or '?'})"

2. Set up the Async Engine and Session

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "postgresql+asyncpg://user:password@localhost/dbname"
engine = create_async_engine(DATABASE_URL)
async_session_maker = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

3. Initialize and Register Endpoints

from fastapi import FastAPI
from autoendpoint.core import AutoEndpoint

app = FastAPI()

@app.on_event("startup")
async def startup():
    async with async_session_maker() as session:
        # Create endpoints for the Hero model
        # Note: In a production app, you might want to manage the session differently
        # enable_graphql defaults to True
        my_endpoints = AutoEndpoint(db_session=session, models=[Hero], enable_graphql=True)
        my_endpoints.init_app(app=app)

Generated Endpoints

For a model named Hero, the following endpoints are automatically generated:

• GET /hero: List records. Supports pagination via query parameters:
  • limit: The maximum number of records to return (default: 10). Set limit=0 to return all records.
  • page: The page number to return (default: 1).
• POST /hero: Create a new record. Primary key is excluded from the request body and expected to be server-side or factory generated.
• GET /hero/{id}: Retrieve a single record by its primary key.
• PUT /hero/{id}: Update all fields of a record (excluding primary key).
• PATCH /hero/{id}: Partially update fields of a record (excluding primary key).
• DELETE /hero/{id}: Delete a record by its primary key.
• GET /hero/unique/{field_name}?value=...: Retrieve a single record by any unique field (e.g., /hero/unique/email?value=[e-mail]). Raises a 400 error if multiple records are found.
• GET /hero/filter/{field_name}?value=...: Retrieve all records matching a specific field and value (e.g., /hero/filter/age?value=30).
• GET /hero/{hero_id}/{relationship_name}: Retrieve related record(s) for a specific record:
  • Returns a list for one-to-many (1:n) relationships (e.g., /user/{user_id}/posts).
  • Returns a single object for one-to-one (1:1) relationships (e.g., /user/{user_id}/profile).
• POST /hero/{hero_id}/{relationship_name}/{target_id}: Link a record to another record in a many-to-many relationship (e.g., /user/{user_id}/groups/{group_id}).
• PATCH /hero/{hero_id}/{relationship_name}/{target_id}: Update the link record itself in a many-to-many relationship (useful if the link table has extra fields).
• DELETE /hero/{hero_id}/{relationship_name}/{target_id}: Unlink a record from another record in a many-to-many relationship.
• POST /graphql: The GraphQL endpoint (if enabled) for querying your models. Includes a string_representation field for each model that reflects its __str__ output.

Multi-database and Schema Support

If your models use a specific database schema (common in PostgreSQL), you can set the metadata.schema on your SQLModel before defining tables or use the AUTOENDPOINT_TEST_SCHEMA environment variable in the sandbox environment.

from sqlmodel import SQLModel
# Set a global schema for all models
SQLModel.metadata.schema = "my_schema"

In the sandbox, you can also use:

export AUTOENDPOINT_TEST_SCHEMA=test
uv run uvicorn sandbox.main:app --reload

FastMCP Compatibility

The generated endpoints are enhanced with description fields for all parameters, making them highly readable and easy to use with FastMCP and other LLM-friendly tools. Each parameter explicitly describes its role (e.g., "The Hero data to create" or "The Hero record to retrieve by id").

Documentation

The project includes Sphinx documentation and test coverage reports.

In GitLab CI, these are automatically generated and hosted via GitLab Pages:

• Documentation: https://autoendpoint-beaddd.gitlab.io/docs/
• Coverage Report: https://autoendpoint-beaddd.gitlab.io/coverage/

Methods are documented using the Google format.

License

Under construction.