Designing a REST API Your Future Self Will Not Hate

You can refactor a controller any time. You cannot refactor an API that a shipped mobile app depends on. Every design decision you make on day one is effectively load-bearing for years.

Version From the Very First Endpoint

/api/v1/projects, not /api/projects. It costs nothing today. Without it, your only options later are breaking every client or maintaining a confusing parallel structure.

Return Consistent Shapes

Every response — success or failure — should have the same top-level structure. Clients then write one parser instead of one per endpoint.

{
  "success": true,
  "data": { },
  "message": null,
  "meta": { }
}

Use Real HTTP Status Codes

Returning 200 OK with {"error": "not found"} forces every client to inspect the body to know whether the request worked. Use 201 for created, 404 for missing, 422 for validation failures, 401 versus 403 correctly. Every HTTP client already understands these.

API Resources, Not Raw Models

Returning a model directly means adding a column silently changes your API payload — and can leak a field you never meant to expose. Laravel API Resources make the contract explicit:

class ProjectResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id'         => $this->id,
            'title'      => $this->title,
            'slug'       => $this->slug,
            'tech_tags'  => $this->tech_tags,
            'published'  => $this->published_at?->toIso8601String(),
        ];
    }
}

Paginate Everything That Grows

Any collection endpoint that can exceed a few dozen records gets pagination from day one. Adding it later is a breaking change for every client.

Dates in ISO 8601, UTC, Always

2026-01-19T09:00:00Z. Not a formatted string, not a local timezone, not a Unix integer some clients will parse in seconds and others in milliseconds. Format for display on the client.

Document as You Build

Not after. A README with a curl example per endpoint beats a beautiful spec that was never finished. The best documentation is the one that exists.