Hub Endpoint Workflow

Use this page as the durable reference for NuxtHub API endpoint work. Use the plan-hub-endpoint skill for the step-by-step planning workflow and backend-guidelines for Laravel conventions.

Scope

NuxtHub API endpoints live under:

routes/hub/
app/Http/Controllers/Hub/
app/Http/Requests/Hub/
app/Http/Resources/Hub/

Related authorization usually lives in app/Policies/. Business rules should live in domain actions, services, or data objects rather than controllers.

Endpoint Shape

Prefer reusable, resource-oriented endpoints with query filters over duplicate feature-specific routes. Index endpoints should paginate with a validated per_page cap.

For single-resource endpoints, prefer implicit route model binding. Use scoped bindings for nested resources so child models are constrained by their parent.

Request Lifecycle

1. Route middleware authenticates the hub request.
2. Policy or role middleware authorizes the action.
3. Form Request validates input.
4. Controller converts validated input to an action call or DTO.
5. Action or service performs business logic.
6. Controller returns an API Resource or response object.

Planning Checklist

• Route alias constant added to app/Core/RouteAliases.php when applicable.
• Route registered in the correct routes/hub/ file.
• Controller follows sibling conventions.
• Form Request owns validation.
• Policy or middleware owns authorization.
• Action/service owns business rules.
• Resource owns response shape.
• Tests cover success, authentication failure, authorization failure, validation, and relevant tenant boundaries.

Verification

Run the focused feature test for the endpoint:

docker compose exec -T core.web php artisan test --compact tests/Feature/Controllers/Hub/YourEndpointTest.php

Run policy or action unit tests when the endpoint introduced non-trivial authorization or business logic.