endpoint
starsforks
How to install endpoint?
ocbunknown/fastapi-claude-template/endpoint
$npx -y skills add ocbunknown/fastapi-claude-template --skill endpointUse when creating or editing a FastAPI endpoint under src/presentation/http/v1/endpoints/<audience>/. Enforces audience-first organization (public/user/admin/internal), the exact parameter-naming convention (data for bodies, query for GET filters), the five-parameter list shape,
SKILL.md
| 1 | # Writing HTTP endpoints (`src/presentation/http/v1/endpoints/<audience>/`) |
| 2 | |
| 3 | Endpoints are **thin adapters**. They have no business logic, no DB access, no validation beyond schema parsing. Their job is `contract → Request → request_bus.send() → OkResponse(contract.from(result))`. |
| 4 | |
| 5 | ## Pick the audience folder first |
| 6 | |
| 7 | Endpoints live under `presentation/http/v1/endpoints/<audience>/` where `<audience>` decides auth: |
| 8 | |
| 9 | | Folder | Router guard | Use for | |
| 10 | |---|---|---| |
| 11 | | `public/` | none | healthcheck, register, login, refresh, public forms | |
| 12 | | `user/` | `Authorization()` (any authenticated user) | `/users/me`, logout, anything user-owned | |
| 13 | | `admin/` | `Authorization("Admin")` | admin user management, moderation, cross-user operations | |
| 14 | | `internal/` | service-to-service stub, `include_in_schema=False` | webhooks, internal APIs | |
| 15 | |
| 16 | **You never attach `Authorization(...)` at the endpoint function level** when the router already enforces it. FastAPI caches the dependency result per request, so declaring `user: Annotated[UserResult, Require(Authorization())]` as a parameter inside a `user/`-audience endpoint is free — it returns the same cached `UserResult` that the router-level guard already validated. |
| 17 | |
| 18 | ## Endpoint file skeleton |
| 19 | |
| 20 | ```python |
| 21 | # src/presentation/http/v1/endpoints/admin/widget.py |
| 22 | from typing import Annotated |
| 23 | |
| 24 | import uuid_utils.compat as uuid |
| 25 | from dishka.integrations.fastapi import DishkaRoute |
| 26 | from fastapi import APIRouter, Query, status |
| 27 | from fastapi import Depends as Require |
| 28 | |
| 29 | from src.application.common.interfaces.request_bus import RequestBus |
| 30 | from src.application.common.pagination import OffsetPagination |
| 31 | from src.application.v1.results import OffsetResult, WidgetResult |
| 32 | from src.application.v1.usecases.widget import ( |
| 33 | CreateWidgetRequest, |
| 34 | SelectManyWidgetRequest, |
| 35 | SelectWidgetRequest, |
| 36 | UpdateWidgetRequest, |
| 37 | ) |
| 38 | from src.common.di import Depends |
| 39 | from src.database.psql.types.widget import WidgetLoads |
| 40 | from src.presentation.http.common.responses import OkResponse |
| 41 | from src.presentation.http.v1 import contracts |
| 42 | |
| 43 | admin_widget_router = APIRouter( |
| 44 | prefix="/widgets", tags=["Admin | Widget"], route_class=DishkaRoute |
| 45 | ) |
| 46 | ``` |
| 47 | |
| 48 | ### Fixed imports |
| 49 | |
| 50 | - `from fastapi import Depends as Require` — the project **always** aliases `Depends` → `Require` to make the intent obvious. |
| 51 | - `from src.common.di import Depends` — this is **Dishka's** `Depends[T]` marker used for DI, different from FastAPI's `Depends`. Use `Depends[RequestBus]` etc. as parameter annotations. |
| 52 | - `from dishka.integrations.fastapi import DishkaRoute` — every `APIRouter` passes `route_class=DishkaRoute` so Dishka can inject into endpoints. |
| 53 | - `tags=["<Audience> | <Resource>"]` — two-word tag with a pipe, e.g. `"Admin | User"`, `"Admin | Widget"`, `"User"`, `"Public"`. |
| 54 | |
| 55 | ## Result → Contract mapping |
| 56 | |
| 57 | Endpoints always hand the client a `Contract`, never a raw `Result`. There are two shapes: |
| 58 | |
| 59 | - **Single item:** `contracts.User.model_validate(result)` — pass the Result instance directly. No `.model_dump()` round-trip needed; `Contract` inherits `from_attributes=True`, so Pydantic reads attributes off the Result object in place. |
| 60 | - **Paginated list:** `result.map(contracts.User.model_validate)` — `OffsetResult.map(fn)` applies `fn` to every item in `.data` and returns a new `OffsetResult[R]` with the same `offset/limit/total`. No manual unpacking, no re-building the envelope. |
| 61 | |
| 62 | The `OffsetResult[T]` envelope is layer-agnostic — defined once in `application/v1/results/base.py` and reused as both the use case return type and the HTTP response type. You use the **application** class for `response_model=OffsetResult[contracts.User]`. There is no `contracts.OffsetResult`. |
| 63 | |
| 64 | ## Parameter naming — non-negotiable |
| 65 | |
| 66 | | HTTP method | Input source | Parameter name | Type annotation | |
| 67 | |---|---|---|---| |
| 68 | | `GET` | query string filters | `query` | `Annotated[contracts.SelectWidgets, Require(contracts.SelectWidgets)]` | |
| 69 | | `POST`/`PATCH`/`PUT`/`DELETE` | JSON body | `data` | `contracts.CreateWidget` (direct, FastAPI parses body automatically) | |
| 70 | | path | path params | `widget_uuid: uuid.UUID` (literal FastAPI path) | — | |
| 71 | | extras for GET | standalone primitives | named (`loads`, `order_by`) | `tuple[WidgetLoads, ...] = Query(default=(), title="...")` | |
| 72 | |
| 73 | **Never use** `body`, `payload`, `params`, `queries`, `input`, `args`. The project is consistent — `query` for GET filters, `data` for mutation bodies. |
| 74 | |
| 75 | ## The five-parameter list shape (`GET /widgets`) |
| 76 | |
| 77 | Every list endpoint uses **exactly** this shape — do not deviate, do not reorder: |
| 78 | |
| 79 | ```python |
| 80 | @admin_widget_router.get( |
| 81 | "", |
| 82 | respons |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
