The Problem
A SaaS business had reached the point where strategic partners needed programmatic access to their platform. The existing product had no API surface — all integrations were done through CSV exports and manual processes, which did not scale and created operational overhead for both sides.
The brief was to design and build an API that could serve multiple external partners, each with different access scopes, without exposing the internal data model directly or creating a maintenance burden when the underlying product changed.
Constraints
- Multiple partners with different authentication requirements (API keys for some, OAuth 2 for others).
- The API needed to be versioned from the start — breakage of existing consumers was not acceptable.
- OpenAPI documentation was a contractual requirement for partner onboarding.
- The internal team had no prior experience maintaining a public API and needed guardrails.
Approach
The API was built as a separate Laravel application routing to the same database, rather than bolted onto the existing product codebase. This allowed the API to evolve independently and reduced the blast radius of product changes.
Key design decisions:
- URI-based versioning (
/api/v1/) — explicit and easy for partners to reason about. - Laravel Sanctum for API token authentication with scoped abilities per partner.
- Dedicated API resource classes acting as an explicit transformation layer — internal model changes do not directly affect API responses.
- Per-partner rate limiting configured at the middleware level.
- OpenAPI 3.0 spec generated from annotations and validated against actual responses in the test suite.
Technical Decisions
The resource transformation layer was the most important structural decision. By explicitly mapping internal models to API response shapes, it decoupled the API contract from the product schema — future product refactoring did not require coordinating API changes with external partners.
A full integration test suite was built that validated responses against the OpenAPI spec automatically, ensuring the documentation stayed accurate as the codebase evolved.
Outcomes
- Multiple partners integrated and actively consuming the API within weeks of launch.
- No breaking changes to the v1 API surface since initial release, despite significant internal product changes.
- Partner onboarding time reduced substantially — the OpenAPI spec served as sufficient documentation for technical teams.
- Internal team confident to add new endpoints independently using established patterns.
- Rate limiting and auth scopes prevented any accidental data exposure across partner accounts.