API conventions for Laravel projects that scale

After building several Laravel APIs across different teams, I've settled on a set of conventions that keep things predictable. These aren't framework features — they're agreements that reduce cognitive load.

Resource classes for every response

Never return raw Eloquent models from your controllers. Always transform them through a Resource class. This gives you a single place to control the output shape and prevents accidental field leakage.

class UserResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at?->toIso8601String(),
        ];
    }
}

Consistent error responses

Define a single error envelope and use it everywhere. Clients should be able to write one error handler that covers the entire API.

Route grouping by domain

Group routes by business domain, not by HTTP verb. This makes it easier to find related endpoints and apply middleware at the right granularity.

These small conventions compound over time. The team moves faster because every file looks familiar.