laravel-api-architect

name

laravel-api-architect

description

Laravel API development, REST endpoints, JSON responses, Sanctum/Passport authentication, Service-Repository pattern. ALWAYS activate when: working with routes/api.php, app/Http/Controllers/Api/, API endpoints, token authentication, mobile backend, API Resource, JsonResponse, FormRequest, Policy. Triggers on: endpoint çalışmıyor, API hatası, API error, 401 unauthorized, 403 forbidden, 422 validation, token expired, login endpoint, register API, CRUD operations, postman, fetch request, axios, mobile backend, webhook, OAuth, JWT, auth guard, rate limit, throttle, response format, pagination API.

Laravel API Architect

Production-grade API development with Service-Repository pattern for PHP 8.4+ and Laravel 12+.

Core Principles

1. Thin Controllers - HTTP concerns only, delegate business logic to Services
2. Service Layer - Business logic, transactions, events
3. Repository Layer - Complex queries (optional, use when needed)
4. Type Everything - Return types, parameter types, property types
5. Form Requests - Validation never in controllers
6. API Resources - Response transformation, never return models directly

Architecture Quick Reference

Layer	Responsibility	Depends On
Controller	HTTP request/response	Services, FormRequests
Service	Business logic, transactions	Repositories, Models, Events
Repository	Complex/reusable queries	Models
Model	Data, relationships, scopes	Other Models only

Essential Patterns

Controller Pattern

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\StoreOrderRequest;
use App\Http\Resources\OrderResource;
use App\Models\Order;
use App\Services\OrderService;
use Illuminate\Http\JsonResponse;
use Symfony\Component\HttpFoundation\Response;

final class OrderController extends Controller
{
    public function __construct(
        private readonly OrderService $orderService
    ) {}

    public function index(): JsonResponse
    {
        $orders = Order::query()
            ->forUser(auth()->id())
            ->with(['items'])
            ->latest()
            ->paginate(15);

        return response()->json(OrderResource::collection($orders));
    }

    public function store(StoreOrderRequest $request): JsonResponse
    {
        $order = $this->orderService->create($request->validated());

        return response()->json(
            new OrderResource($order),
            Response::HTTP_CREATED
        );
    }

    public function show(Order $order): JsonResponse
    {
        $this->authorize('view', $order);
        
        return response()->json(
            new OrderResource($order->load(['items', 'payments']))
        );
    }

    public function destroy(Order $order): JsonResponse
    {
        $this->authorize('delete', $order);
        $order->delete();
        
        return response()->json(null, Response::HTTP_NO_CONTENT);
    }
}

Service Pattern

<?php


namespace App\Services;

use App\Events\OrderCreated;
use App\Models\Order;
use Illuminate\Support\Facades\DB;

final class OrderService
{
    public function create(array $data): Order
    {
        return DB::transaction(function () use ($data): Order {
            $order = Order::query()->create([
                'user_id' => auth()->id(),
                'status' => OrderStatus::Pending,
                'total' => $data['total'],
            ]);

            $order->items()->createMany($data['items']);

            event(new OrderCreated($order));

            return $order->load('items');
        });
    }
}

Form Request Pattern

<?php


namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

final class StoreOrderRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'total' => ['required', 'numeric', 'min:0'],
            'items' => ['required', 'array', 'min:1'],
            'items.*.product_id' => [
                'required',
                Rule::exists('products', 'id')->where('active', true),
            ],
            'items.*.quantity' => ['required', 'integer', 'min:1', 'max:100'],
        ];
    }
}

API Resource Pattern

<?php


namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

final class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'status' => $this->status->value,
            'total' => $this->total,
            'created_at' => $this->created_at->toISOString(),
            
            // Conditional relationships
            'user' => new UserResource($this->whenLoaded('user')),
            'items' => OrderItemResource::collection($this->whenLoaded('items')),
            
            // Conditional attributes
            'can_cancel' => $this->when(
                $request->user()?->can('cancel', $this->resource),
                true
            ),
        ];
    }
}

References

Load detailed patterns as needed:

Topic	Reference	When to Load
Sanctum authentication	references/sanctum.md	Token auth, SPA auth, abilities
Passport OAuth	references/passport.md	OAuth2, third-party apps
Service-Repository details	references/service-repository.md	Complex business logic

Quick Commands

# Create with best practices
php artisan make:model Order -mfsc          # Model, migration, factory, seeder, controller
php artisan make:request StoreOrderRequest
php artisan make:resource OrderResource
php artisan make:policy OrderPolicy --model=Order

# API Routes
php artisan route:list --path=api

# Format code
./vendor/bin/pint

Remember

• Use ->query() for IDE completion: Order::query()->where(...)
• Use final class for services and controllers
• Use readonly constructor properties
• Use match over complex if/else
• Use Enums for status fields
• Always return JsonResponse, never raw arrays
• Use HTTP status constants: Response::HTTP_CREATED