laravel-api-architect_skill

Overview

This skill guides production-grade Laravel API development using the Service-Repository pattern, strict typing, FormRequests, API Resources, and token authentication best practices. It focuses on REST endpoints, JSON responses, and secure mobile/backend integrations with Sanctum or Passport. Use it to enforce thin controllers, robust services, and consistent response formats across your API.

How this skill works

The skill inspects API-related files and routes (routes/api.php, app/Http/Controllers/Api/, FormRequests, Resources, Policies) and recommends concrete patterns and fixes for controllers, services, repositories, validation, and auth. It detects common API errors (401/403/422), token issues, response format problems, and insecure or inconsistent endpoints, then suggests code-level changes and commands. It provides examples for controllers, services, form requests, resources, and quick artisan commands to scaffold best-practice code.

When to use it

• Working on routes/api.php or adding API routes
• Building or debugging REST endpoints, JSON responses, or mobile backends
• Implementing token authentication (Sanctum/Passport) or OAuth/JWT flows
• Creating FormRequests, API Resources, Policies, or JsonResponse handling
• Encountering API errors: 401 unauthorized, 403 forbidden, 422 validation, token expired
• Integrating with clients: Postman, fetch, axios, webhooks, or mobile apps

Best practices

• Keep controllers thin: delegate business logic to Services and use FormRequests for validation
• Type everything: parameter, return, and readonly constructor property types for PHP 8.4+
• Use API Resources to transform responses and never return Eloquent models directly
• Wrap complex queries in Repositories and use transactions in Services for data consistency
• Return JsonResponse with HTTP status constants and use policies for authorization checks
• Use artisan shortcuts to scaffold Model, Request, Resource, and Policy and run pint for formatting

Example use cases

• Build a mobile login/register backend with Sanctum and token ability checks
• Create CRUD endpoints for Orders using OrderService, StoreOrderRequest, and OrderResource
• Debug a 422 validation error by verifying FormRequest rules and request shape from axios or fetch
• Fix 401/403 by checking auth guard, token expiry, and Policy authorization calls
• Implement paginated index endpoints returning Resource collections with conditional relationships