api-endpoint

api-endpoint

Grounded corpus: endpoint-shape decisions (pagination, error shape, idempotency, rate limits) are grounded via the api-design corpus — ./scripts-run <skills-root>/corpus-grounding/scripts/ground search --manifest <skills-root>/api-design/data/manifest.json "<concern>".

When to use

Use this skill when the user asks to create a new API endpoint, REST route, or HTTP handler.

Do NOT use when:

• Modifying existing endpoints — use the code-refactoring skill.
• API design decisions (versioning, deprecation, contract shape) — use api-design.

Stack routing

Detect the stack, then hand off to the matching carve-out skill for the framework-specific procedure (file layout, validation primitive, response-shaping convention).

If the project doc folder (agents/) has an endpoint-creation guide, that is the source of truth — read it before generating code.

Procedure: Create an API endpoint (stack-neutral)

1. Read project docs — Check ./agents/ and AGENTS.md for endpoint conventions, routing layout, response shape.
2. Detect stack and route to the carve-out per the table above.
3. Plan the endpoint — method, path, request shape, response shape, auth requirement, idempotency.
4. Create the route registration in the project's routing surface (route file, decorator-annotated handler, file-based router).
5. Create the request handler / controller — thin; delegate business logic to a service / use-case.
6. Validate input at the boundary via the framework's validation primitive (FormRequest, Zod, class-validator, Pydantic, struct-tag validators, etc.) — never inline ad-hoc if checks.
7. Authorize the action via the framework's authz primitive (Policy, voter, guard, middleware, route dependency).
8. Shape the response through a transformer / serializer / DTO — never return raw ORM entities.
9. Document the endpoint (OpenAPI annotations / generated spec / project doc).
10. Verify — run the project type-checker + targeted tests + smoke probe (curl / Bruno / Postman / integration test).

Conventions (apply on every stack)

• One handler, one responsibility — prefer single-purpose handlers over multi-action controllers when the framework supports it.
• No business logic in the handler — delegate to a service / use-case layer.
• Validate at the boundary — never trust raw request data inside the handler.
• Authorize every state-changing action — no unprotected mutating endpoints.
• Shape responses through a transformer — DTO, serializer, API resource, response model — never expose raw ORM entities.
• Version the API surface explicitly (/v1/, header, content-type) — don't rely on implicit versioning.

Stack-specific procedures

For Laravel projects (the most fully-fleshed-out carve-out in this package), see laravel-api-endpoint — covers single-action controllers, FormRequest, Resource, Policy, CollectionFormRequest, OpenAPI attributes, and the versioned route layout.

For other stacks, read the matching carve-out from the table above and combine with the project's agents/ docs.

Output format

1. Generated files — route registration, handler, request validator, response shaper, authorization rule.
2. Test file with happy path and validation-error cases (using the project's test framework).
3. Summary of created files and their locations.

Gotcha

• Don't forget to register the route — creating the handler without the route is a common miss.
• Always check if a similar endpoint already exists — duplicates cause confusion.
• Validation rules must match the documented contract (OpenAPI / schema / typed client) — keep them in sync.
• Response shapes are part of the public contract — adding a field is additive; renaming or removing is breaking.

Do NOT

• Do NOT put business logic in the handler — delegate to services / use-cases.
• Do NOT skip request validation — every handler validates at the boundary via the framework's primitive.
• Do NOT return raw ORM entities — always go through a transformer / serializer / response model.
• Do NOT create unprotected state-changing endpoints — authorize every mutation.
• Do NOT improvise framework idioms — read the carve-out (laravel-api-endpoint, nextjs-patterns, etc.) for the stack-correct shape.

Auto-trigger keywords

• create endpoint
• new API route
• route handler
• controller creation
• REST endpoint
• add endpoint