# Python API Endpoint Creator

> Creates FastAPI endpoints with layered architecture (Router → Service → Repository). Use when creating new API endpoints, CRUD operations, or scaffolding a new domain module in a FastAPI project.

- Skill: `c0x12c/python-api-endpoint-creator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add c0x12c/python-api-endpoint-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/c0x12c/python-api-endpoint-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: c0x12c (https://skillmd.com/u/c0x12c)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/c0x12c/python-api-endpoint-creator

---


# Python API Endpoint Creator

Creates complete FastAPI endpoints following strict layered architecture patterns.

## When to Use

- Creating a new REST API endpoint from scratch
- Adding CRUD operations for a new domain entity
- Setting up the full stack: Router → Service → Repository → Tests
- Scaffolding a new domain module

## Process

1. **Pydantic Schemas** — Create/Update/Response in `schemas.py`
2. **SQLAlchemy Model** — with SoftDeleteMixin in `models.py`
3. **Repository** — async CRUD with soft delete in `repository.py`
4. **Service** — business logic, HTTPException for errors in `service.py`
5. **Dependencies** — `get_db`, `get_service` in `dependencies.py`
6. **Router** — thin endpoints, Depends() for everything in `router.py`
7. **Tests** — httpx AsyncClient tests in `tests/`

> See code-patterns.md for complete templates for each file.

## Architecture

```
Router (APIRouter)  →  Service  →  Repository  →  Database
      ↓                  ↓            ↓
  Depends()        Business logic  SQLAlchemy
  Pydantic schemas HTTPException   AsyncSession
  Status codes     Validation      Soft delete
```

## Hard Rules

- **POST for all mutations** — GET for reads, POST for create/update/delete
- **Query params for IDs** — `?id=xxx`, never path params `/{id}`
- **Routers are thin** — just delegation, no business logic
- **Services raise HTTPException** — for expected errors (404, 409, 422)
- **Repositories handle soft delete** — filter `deleted_at.is_(None)` in all queries
- **`async def` for all endpoints** — unless CPU-bound

## Gotchas

- **Forgetting `response_model` makes your API leak internal fields.** Always set `response_model=YourSchema` on endpoints. Without it, FastAPI serializes the raw return value, which may include `hashed_password`, `deleted_at`, or other internal fields from your SQLAlchemy model.

- **`Depends()` creates a new instance per request — not a singleton.** If your service holds state, it will be lost between requests. Services should be stateless. If you need shared state, use app state or a cache.

- **`await db.commit()` in the dependency, not in the repository.** The `get_db` dependency handles commit/rollback. If you also commit inside the repository, you get double-commit bugs or premature commits before all operations complete.

- **422 errors from Pydantic are opaque by default.** Override the `RequestValidationError` handler to return field-level errors. The default just says "validation error" with no useful detail for the frontend.

- **Missing `status_code=201` on create endpoints.** FastAPI defaults to 200. Explicitly set `status_code=status.HTTP_201_CREATED` on POST create routes and `status_code=status.HTTP_204_NO_CONTENT` on delete routes.