Skip to content
Skills Library
Programming · Building & coding

api-endpoint

/api-endpoint

Use when creating an API endpoint or HTTP route handler — detects the project stack and routes to the matching carve-out (laravel-api-endpoint, nextjs-patterns, symfony-workflow).

Licence
MIT
Last repository change
26.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when creating an API endpoint or HTTP route handler — detects the project stack and routes to the matching carve-out (laravel-api-endpoint, nextjs-patterns, symfony-workflow).

Original author description

Use when creating an API endpoint or HTTP route handler — detects the project stack and routes to the matching carve-out (laravel-api-endpoint, nextjs-patterns, symfony-workflow).

How it works

  1. When to use
  2. Stack routing
  3. Procedure: Create an API endpoint (stack-neutral)
  4. Conventions (apply on every stack)
  5. Stack-specific procedures
  6. Output format
  7. Gotcha
  8. Do NOT
  9. Auto-trigger keywords
Original SKILL.md headings · 92 lines, 749 words
SKILL.md preview
---
model_tier: medium
name: api-endpoint
description: "Use when creating an API endpoint or HTTP route handler — detects the project stack and routes to the matching carve-out (laravel-api-endpoint, nextjs-patterns, symfony-workflow)."
domain: engineering
workspaces:
  - engineering
packs:
  - engineering-base
---

# api-endpoint


> **Grounded corpus:** endpoint-shape decisions (pagination, error
> shape, idempotency, rate limits) are grounded via the
> [`api-design`](../api-design/SKILL.md) corpus — `node
> <skills-root>/corpus-grounding/scripts/ground.mjs 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`](../api-design/SKILL.md).

## 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).

| Detected stack | Carve-out skill |
|---|---|
| Laravel (`artisan` + `composer.json` with `laravel/framework`) | [`laravel-api-endpoint`](../laravel-api-endpoint/SKILL.md) |
| Symfony (`bin/console` + `composer.json` with `symfony/framework-bundle`) | [`symfony-workflow`](../symfony-workflow/SKILL.md) |
| Next.js (`next` in `package.json`) | [`nextjs-patterns`](../nextjs-patterns/SKILL.md) |
| Express / Fastify / NestJS / plain Node | follow project conventions in `agents/` + `package.json scripts` |
| FastAPI / Django / Flask | follow project conventions in `agents/` + `pyproject.toml` |
| Go (`net/http`, `gin`, `echo`, `fiber`) | follow project conventions in `agents/` + `go.mod` |
| Rust (`axum`, `actix-web`, `rocket`) | follow project conventions in `agents/` + `Cargo.toml` |

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`](../laravel-api-endpoint/SKILL.md) — 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
Files in this package (2)
  • SKILL.md 6 KB
  • evals/triggers.json 3 KB

Versions

RepositoryScoreLicence
This page · event4u-app/agent-config90MIT
proteanhq/protean100Apache-2.0
globalmpc/backendskills100MIT
globalmpc/backendskills95MIT

Database snapshot: 13.11.2026 · package version c573ac72bd45 (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

  • 90add-api-endpoint
    Use when a ticket asks to add or extend an HTTP/API endpoint — a new route, handler, or RPC method — with request validation and a defined response. Invoke for "add a POST /things endpoint", "expose a list API", or "add a field to the X response".
  • 100laravel-api-endpoint
    Use when creating a new Laravel API endpoint — Controller, FormRequest, Resource, route, Policy, OpenAPI annotations — versioned route layout, single-action `__invoke` controllers.
  • 95webiny-http-route
    Adding custom HTTP routes to the API with <Api.Route> and HttpRouteHandler. Use this skill when the developer wants to expose a custom HTTP endpoint (GET, POST, PUT, etc.) on the API alongside the GraphQL handler, implement a route handler with full DI support, or register a…
  • 100add-web
    TRIGGER when user asks to add or modify a web handler, HTML page, file download, or raw HTTP endpoint that works with http.ResponseWriter/http.Request.
  • 100php-ecosystem-reference
    Use when picking a non-Laravel PHP tool — Symfony components, API Platform, or Slim — and routing to implementation. Do NOT use for Laravel (laravel-expert).
  • 100add-v1-endpoint
    Add a new route under /v1/... to the AerolVM HTTP server. Walks through DTOs, handler, route registration, service-layer call, tests, and the idempotency check. Use when the user asks to "add a v1 endpoint", "add an API route", "add a new HTTP handler", or describes a new…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.