laravel-api-endpoint

laravel-api-endpoint

When to use

Use this skill when the project is Laravel (detected via artisan + composer.json with laravel/framework) and the user asks to create a new API endpoint, REST route, or controller action.

Routed in from api-endpoint once the stack is detected as Laravel.

Do NOT use when:

• Modifying existing endpoints — use the code-refactoring skill.
• API design decisions — use api-design.
• The project is Symfony / Next.js / FastAPI / etc. — go back to api-endpoint and pick the right carve-out.

Procedure: Create a Laravel API endpoint

1. Read project docs — Check ./agents/ and AGENTS.md for controller conventions, resource patterns, routing.
2. Create route — Add to the correct routes/api.php or module route file (routes/api/v{N}/{domain}.php).
3. Create controller — Single-action invokable controller, thin, delegate logic to a service.
4. Create FormRequest — Validate all input at the boundary; authorize via Policy in authorize().
5. Create Resource — Transform model output via API Resource (never raw arrays / models / response()->json()).
6. Create Policy — If authorization is needed and no Policy exists yet.
7. Verify — Run PHPStan, run tests, confirm response shape matches conventions.

What to generate

1. Controller — Single Action (invokable). Read agents/reference/docs/controller.md and ../../../docs/guidelines/php/controllers.md.
2. FormRequest — Validation rules, authorize() via policies. Read ../../../docs/guidelines/php/validations.md.
3. Resource — JSON response transformation. Read agents/reference/docs/api-resources.md.
4. Route — Add to the correct versioned route file.
5. Policy — If authorization is needed.
6. Filter classes — If it's a list endpoint with filtering. Read agents/reference/docs/query-filter.md (if it exists).

Conventions

• Controllers are thin — delegate to Services.
• Every controller MUST return an API Resource — never raw arrays, models, or response()->json().
• Controllers type-hint the return value as the Resource class (e.g. ): ProjectResource).
• Use Resource::make() for single items, Resource::collection() for lists.
• Use method injection on __invoke() for new controllers.
• Use DTOs for data transfer between layers.