Pillar
API Design
How APIs outgrow the design they shipped with, and what to fix first.
- 51Articles
- 9 hrsOf reading
- 39Videos
- 7Guides
- 22Packages
Most APIs are not badly built. They were built once, correctly, for a product that then changed underneath them. The endpoint everyone complains about is rarely slow because of the code inside it. It is slow because it is still answering a question nobody asks any more, and three clients now depend on the shape of that answer.
Which is why I do not open with a rewrite. I find the call that is actually costing you, which is almost never the one the dashboard is shouting about, and stabilise that one first. Contracts before code. Get the shape wrong and faster only means wrong sooner.
And most of what keeps an API safe to change was written down years ago. Problem details, idempotency keys, deprecation headers, rate limits a client can read: the standards exist, and they only pay off when both ends honour them, so I build them into the API and into the SDK that calls it.
What is here: those standards on both ends of the wire, versioning that does not need a v2, why fixing a bug can break your consumers, validating data you did not design and cannot trust, and what to do when CRUD runs out of room. Written from APIs in production, including the ones that broke.
Start here
A route through it, in order.
- 1
Most of Your API Has Already Been Designed
Error formats, retries, lost updates, webhook signing: the IETF has already answered them. api-toolbox brings those answers to Laravel, one RFC per feature.17 min read - 2
Fixing a Bug Can Be a Breaking Change
Your consumers built against your behaviour, not your documentation. Correcting a bug they worked around is an outage you shipped on purpose.7 min read - 3
Most of Your SDK Has Already Been Designed, Too
Retries, rate limits, pagination, lost updates: the API already tells your client what to do. sdk-toolbox makes a PHP SDK listen, one RFC at a time.19 min read - 4
Accepting Data You Don't Control
Webhooks and callbacks you did not design. An ingest server in Laravel 13 that owns the envelope, stores the payload whole, and validates where failure means a retry, not data loss.14 min read
Same subject
API Design, in every other format.
Videos · 39
All 39 videos →
Archive
Everything in API Design, newest first.
You Can't Deprecate a Field With a Header
RFC 9745's Deprecation header covers whole resources, so a field changing shape has no HTTP signal. Where that deprecation goes instead, and where the header is exactly right.
Both Ends of the Wire
I built a small CRM API on api-toolbox and its SDK on sdk-toolbox, in one repository, tested against each other. My own two libraries disagreed within a day.
Fixing a Bug Can Be a Breaking Change
Your consumers built against your behaviour, not your documentation. Correcting a bug they worked around is an outage you shipped on purpose.
Most of Your SDK Has Already Been Designed, Too
Retries, rate limits, pagination, lost updates: the API already tells your client what to do. sdk-toolbox makes a PHP SDK listen, one RFC at a time.
An Example App That Needs Its Features
Flagpole is a feature flag service built on kit, where every HTTP standard is there because the domain needs it. Building it found four bugs that kit's own tests never caught.
A Laravel API Starter Kit That Keeps Its Promises
Starter kits are right on the day you install them and drift from then on. Kit now checks its own promises in CI, so the docs, spec, errors and dependencies stay true.
Most of Your API Has Already Been Designed
Error formats, retries, lost updates, webhook signing: the IETF has already answered them. api-toolbox brings those answers to Laravel, one RFC per feature.
Your endpoint, as an agent sees it
An agent never reads your API. It reads a flattened projection of it, and the flattening loses things you did not know were losable. Here is how to look at yours.
Accepting Data You Don't Control
Webhooks and callbacks you did not design. An ingest server in Laravel 13 that owns the envelope, stores the payload whole, and validates where failure means a retry, not data loss.
Building Bulletproof Laravel APIs using Schema-First Contract Validation
Stop letting undocumented fields into your Laravel API. Write the JSON Schema first, then enforce it in middleware, DTOs, and your Pest test suite.
The Tips Behind API Artisan: Building Laravel APIs Developers Actually Want to Use
Practical tips for building Laravel APIs developers trust: contract-first design, versioning, RFC 9457 errors, idempotency and more. Free book inside.
Server-Side Rate Limiting in Laravel with Fingerprint.dev
Learn how to build device-based rate limiting in Laravel with Fingerprint.dev, Redis caching, and custom middleware to avoid the limits of IP-based throttling.