Building REST APIs with Modern PHP: Routing, Validation and Auth

Building REST APIs with modern PHP is a genuinely pleasant experience in 2026, which would have sounded like a joke to anyone who wired JSON endpoints together by hand in the old days. Typed request objects, enums for status fields, first-class attribute routing and mature framework tooling mean the boilerplate has largely evaporated. What has not changed is that the difference between a good API and a frustrating one lives in the details: predictable URLs, validation that fails loudly and early, authentication that is boring in the best sense, and error responses a client can actually program against. This post walks through each layer with the decisions that matter.

Routing: predictable beats clever

REST routing is a solved problem; your job is to not un-solve it. Resources are plural nouns, identifiers live in the path, verbs come from HTTP methods, and filtering belongs in the query string. In a framework like Laravel or Symfony, PHP attributes keep the route definition next to the code it serves:

final class OrderController
{
    #[Route('/api/orders', methods: ['GET'])]
    public function index(Request $request): JsonResponse { /* ... */ }

    #[Route('/api/orders/{id}', methods: ['GET'])]
    public function show(string $id): JsonResponse { /* ... */ }

    #[Route('/api/orders', methods: ['POST'])]
    public function store(CreateOrderRequest $request): JsonResponse { /* ... */ }
}

Version your API from day one, either in the path (/api/v1/orders) or a header, because the cost of adding versioning later, after clients exist, is far higher than the cost of a v1 segment you may never increment. Resist deeply nested routes; /customers/42/orders/17/items/3 is harder to consume and to authorise than a flat /order-items/3 with the relationships in the payload.

Validation: reject bad input at the boundary

Every request body is untrusted text until proven otherwise. The modern pattern is to convert raw input into a typed object at the edge of the application, so everything past the controller works with real types rather than nested arrays. Framework validators make the rules declarative:

final class CreateOrderRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'customer_id' => ['required', 'uuid', 'exists:customers,id'],
            'items' => ['required', 'array', 'min:1'],
            'items.*.sku' => ['required', 'string', 'max:64'],
            'items.*.quantity' => ['required', 'integer', 'between:1,999'],
            'currency' => ['required', new Enum(Currency::class)],
        ];
    }
}

Two habits make validation genuinely protective rather than decorative. First, validate structure and domain rules, not just types: a quantity of a million passes an integer check but should still be rejected. Second, return all the failures at once. A client that fixes one field, resubmits, and discovers the next error, five round-trips in a row, is dealing with a hostile API. Backing enums like Currency with native PHP enums means the same definition drives validation, serialisation and business logic, with no string drift between them.

Authentication: tokens, done boringly

For most APIs the right answer is bearer tokens over HTTPS, and the interesting decision is only which flavour. Opaque random tokens stored hashed in the database (the Laravel Sanctum model) are simple, revocable and ideal for first-party clients. Stateless JWTs suit service-to-service traffic and horizontally scaled fleets, at the price of harder revocation, so keep their lifetimes short and pair them with refresh tokens. Full OAuth 2.1 earns its complexity only when third parties need delegated access to user data.

Whichever you pick, the implementation rules are constant: transport tokens only in the Authorization: Bearer header, never in URLs where they leak into logs; hash stored tokens like passwords; compare secrets with hash_equals(); and rate-limit authentication endpoints before anything else. Keep authentication (who is calling) separate from authorisation (what they may do), and enforce the latter close to the resource, so that a policy class, not a route middleware stack, is the single place that knows who may view an order.

Responses: one shape, everywhere

Clients program against the shape of your JSON, so pick one shape and never deviate. A resource endpoint should return the resource under a stable key, with pagination and other metadata alongside rather than mixed in:

{
    "data": [
        { "id": "01J...", "status": "shipped", "total": { "amount": 4200, "currency": "EUR" } }
    ],
    "meta": { "page": 2, "per_page": 25, "total": 1180 }
}

A transformation layer, API Resources in Laravel, serialisation groups in Symfony, or plain hand-written mapper classes, is non-negotiable. Serialising ORM entities directly couples your public contract to your database schema, and the first internal refactor becomes a breaking API change. In the mapper, be deliberate about types: money as integer minor units plus a currency code, timestamps as UTC ISO 8601 strings, booleans as booleans rather than 0 and 1. Use the status codes the spec gave you: 201 with a Location header for creation, 204 for deletion, 422 for validation failures, and 404 for both missing resources and resources the caller may not know exist.

Errors: the part clients remember

Error responses deserve the same design attention as success responses, because integrators spend most of their debugging time looking at them. Adopt a single error envelope, ideally the RFC 9457 problem-details format, and use it for every failure from validation to rate limiting:

{
    "type": "https://api.example.com/errors/validation",
    "title": "Validation failed",
    "status": 422,
    "errors": {
        "items.0.quantity": ["Must be between 1 and 999."]
    }
}

Wire this through a global exception handler so unexpected errors also produce the envelope, with a generic message and a logged correlation ID rather than a stack trace. Leaking internal exception messages is both a security problem and a compatibility trap, because clients start parsing them.

The details that separate solid from fragile

• Idempotency keys on POST endpoints that create side effects, so a retried payment request charges once.
• Rate limiting with honest headers (Retry-After, remaining-quota headers) so clients can back off intelligently.
• Cursor pagination for large or frequently changing collections, since offset pagination skips or duplicates rows under concurrent writes.
• An OpenAPI document generated from attributes or maintained alongside the code, kept honest by contract tests in CI.
• Consistent naming: pick snake_case or camelCase for JSON keys once, and enforce it in review.

The takeaway

Modern PHP gives you typed request objects, enums, attributes and mature frameworks; none of it forces you to design a good API. The design is the checklist above: predictable routes, boundary validation, boring token auth, one response shape, one error shape, and the operational details, idempotency, rate limits, pagination, that only hurt when they are missing. Get those right and the implementation language disappears from the conversation, which is exactly what you want.