api-endpoints
/api-endpoints
End-to-end workflow for adding or changing a backend API endpoint — which module the serializer and view belong in, URL registration, OpenAPI client regeneration, and typed consumption from the frontend. Use when adding, changing, or removing a DRF endpoint or serializer.
- Author
- overmind-core ↗
- Repository
- overmind ↗
- Licence
- AGPL-3.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.
What it does and when to use it
End-to-end workflow for adding or changing a backend API endpoint — which module the serializer and view belong in, URL registration, OpenAPI client regeneration, and typed consumption from the frontend. Use when adding, changing, or removing a DRF endpoint or serializer.
Original author description
End-to-end workflow for adding or changing a backend API endpoint — which module the serializer and view belong in, URL registration, OpenAPI client regeneration, and typed consumption from the frontend. Use when adding, changing, or removing a DRF endpoint or serializer.
How it works
- 1. Serializer and view go in the surface's own module
- 2. Register the route
- 3. Regenerate the client
- 4. Register the API class in client.ts
- 5. Consume through the client, never raw fetch
- Rules
SKILL.md preview
---
name: api-endpoints
description: End-to-end workflow for adding or changing a backend API endpoint — which module the serializer and view belong in, URL registration, OpenAPI client regeneration, and typed consumption from the frontend. Use when adding, changing, or removing a DRF endpoint or serializer.
---
# Adding or changing an API endpoint
The frontend consumes the backend exclusively through the generated typescript-fetch client at `frontend/src/openapi/`. Every API change runs the full loop below.
## 1. Serializer and view go in the surface's own module
`overbae/api/` is one module per surface — `eval_views.py`/`eval_serializers.py`, `datasets.py`/`dataset_serializers.py`, `optimizer.py`, `billing.py`, `otlp.py`, and so on. `views.py` and `serializers.py` are the legacy monoliths; a new surface gets its own module rather than growing them.
Never return a raw dict from a view — request and response shapes are serializers. Keep business logic in `services/` or on the model; annotate with `@extend_schema` where drf-spectacular needs help.
Expected input failures may use `core.errors.InputValidationError` with an authored public `detail`. Never build that detail from a caught exception, provider response or stored diagnostic. Return the authored detail for known failures; log unexpected exceptions server-side and return a fixed message. Apply the same boundary to MCP adapters.
## 2. Register the route
`overbae/urls.py`, on the `DefaultRouter` for viewsets:
```python
router.register(r"widgets", WidgetViewSet, basename="widget")
```
or in `urlpatterns` for plain views.
## 3. Regenerate the client
```bash
make generate_api_client
```
Settings refuse to load without Modal tokens when `.env` has none: prefix with `MODAL_TOKEN_ID=dummy MODAL_TOKEN_SECRET=dummy` — the schema step never talks to Modal.
Runs `manage.py spectacular` → dockerized `openapi-generator-cli` → rewrites `frontend/src/openapi/{apis,models}`.
The Compose frontend uses polling because Docker bind mounts can miss files recreated by generation. A method present on disk but missing at runtime can be a stale Vite transform: check the JavaScript served at `/src/openapi/apis/<Api>.ts`. Recreate the frontend with `docker compose up -d --no-deps frontend` after changing its watcher environment; restarting alone does not apply environment changes.
## 4. Register the API class in `client.ts`
```typescript
import { WidgetsApi } from "./openapi";
export class API {
widgets: WidgetsApi;
constructor(private cfg: Configuration) {
this.widgets = new WidgetsApi(this.cfg);
}
}
```
## 5. Consume through the client, never raw fetch
```typescript
import api from "@/client";
import type { Widget } from "@/openapi";
const widget: Widget = await api.widgets.widgetsRetrieve({ id });
```
Hardcoded URLs and bare `fetch`/`axios` bypass auth middleware and typing. Response types come from `frontend/src/openapi/models/` — never redeclare a type that already exists there.
## Rules
- Never hand-edit anything under `frontend/src/openapi/` — a hook blocks it under Claude Code, and the next regeneration would overwrite it anyway.
- A DRF view docstring becomes the OpenAPI operation `description`, so editing one changes the generated client. Prefer an explicit `@extend_schema(summary=...)`.
Versions
The database has no other skills named api-endpoints.
Database snapshot: 13.11.2026 · package version 3aa9ea85f913 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 86add-resource
Add a REST resource to this Django REST Framework API (model, migration, admin, serializer, viewset, routes, OpenAPI schema and tests). Use when the user asks for a new endpoint, a new kind of record the API stores, or a new app. - 100django-rest-framework-patterns
Django REST Framework — ViewSets and routers, serializer boundaries, the request-flow ladder, fixing serializer N+1 in get_queryset, drf-spectacular, django-filter, SimpleJWT, pagination. Use when building or reviewing a Django REST API. - 98improving-drf-endpoints
Use when editing, reviewing, or auditing DRF viewsets and serializers in PostHog. Triggers on files in posthog/api/, products/*/backend/api/, products/*/backend/presentation/, or any file importing rest_framework. Covers field typing, schema annotations, enum collision fixes,… - 100design-http-api
Use when adding or changing HTTP endpoints, or when the frontend needs typed calls — sets the OpenAPI 3.1 contract, RFC 9457 errors, cursor pagination, idempotency keys, versioning, and a generated typed client behind the frontend fetcher seam. - 100document-api-endpoint
Use when reconciling an API endpoint''s generated OpenAPI schema and declared response types with its actual runtime response. Not for general API documentation: use docs-and-adrs. - 100api-endpoint
Rules for HTTP API endpoints. Use when adding or changing any endpoint (route, request or response shape, status codes), especially login and ones that read or change other users' data.