标签：#apidesign

When you're building a multi-tenant SaaS, the first architectural question is usually: how do you keep tenant data isolated? The options range from separate databases per tenant (maximum isolation, maximum cost) to a shared database with row-level filtering (minimum cost, more careful coding required). But there's an equally important question that gets less attention: how does your API know which tenant context a request belongs to? This post covers a pattern we've used in production: a custom request header for tenant scoping, combined with JWT authentication. Simple to implement, easy to audit, and flexible enough to support multi-tenant access from a single user account. The Three Common Approaches 1. Subdomain-based ( tenant.yourdomain.com ) The tenant is encoded in the hostname. Each subdomain routes to the same backend, which extracts the tenant from the Host header. Good: Intuitive, visible in the URL. Bad: Requires wildcard TLS certs, more complex DNS setup, awkward in development, doesn't work for mobile API clients the same way. 2. URL path-based ( /api/tenants/{tenantId}/... ) The tenant identifier is part of every route path. Good: RESTful, self-documenting. Bad: Bloats all route definitions, requires every endpoint to include the tenant segment, makes API versioning messier. 3. Header-based ( x-tenant-id: <id> ) A custom header carries the tenant context. Routes stay clean. The tenant scope is resolved in middleware before the handler runs. Good: Routes stay simple, middleware handles scoping uniformly, works well with JWT auth, easy to test. Bad: Less visible (the tenant isn't in the URL), requires clients to always include the header. We use the header approach. The Implementation The API accepts two forms of auth: A JWT token in the Authorization header — identifies who is making the request A tenant ID in the x-tenant-id header — identifies on behalf of which tenant POST /api/v1/members Authorization: Bearer eyJhbGciOiJIUzI1NiIs... x-tenant-id: ten

I have just finished writing API Artisan: A Guide to Building APIs with Laravel , and I am giving it away for free. Before you commit to 300-odd pages, let me give you the short version: the tips, patterns, and small decisions that separate an API that technically works from one that developers are genuinely happy to depend on. None of this needs more hardware, a different framework, or a bigger team. It needs you to point your attention at the right things. These are the ones I keep coming back to. Start by measuring the right thing Ask most teams how they know their API is good and you get a single question back: does it work? Can I hit this endpoint and get a response? That question is necessary, and it is nowhere near enough. The question I want you to ask instead is whether your API is liveable with. Can a developer read your docs, understand your auth model, make a successful request, and handle an error without contacting support, trawling a forum, or guessing what a status code is trying to tell them? The gap between "works" and "liveable with" never shows up in a sprint retro, but it shows up everywhere else: in support volume, in integration timelines that overrun, and in the quiet moment a developer decides to build around your API rather than with it. Everything else in the book hangs off one mindset shift: an API is a product. It has users. Treat it as an implementation detail and it will behave like one. It will change without warning when your internals change, and it will be inconsistent because different people wrote different parts on different days with different conventions. Write the contract before the code The natural way to build an endpoint is to write the handler, return some data, and document it afterwards if there is time. It feels efficient, and in the short term it is. The problem is what it produces: a contract that was never designed, only discovered. Let me show you the trap, because I have watched it catch good developers. You have

Every interface you create is a constraint on future behavior. Every abstraction emphasizes certain patterns and discourages others. You are not just building tools. You are shaping how people think about problems. I have been paying attention to how API design encodes values, not just technical decisions, but philosophical ones. What Your API Communicates Consider these design choices: Mutability vs Immutability. Do you encourage stateful modification or pure functions? This is not just about performance. It is a philosophy about side effects and reasoning. If your default is mutable state, you are telling users that local mutation is fine, that they can reason locally. If your default is immutability, you are telling them to think about data flow. Explicit vs Implicit. Do you make users specify parameters or infer from context? This trades convenience for transparency. I lean toward explicitness. Magic is convenient until you need to debug it. Fail Fast vs Fail Safe. Do you throw exceptions or return error codes? This encodes beliefs about who should handle errors and when. Fail-fast says "don't let bad state propagate." Fail-safe says "keep running if you can." Both are defensible, but they lead to very different code. My Design Values When I build libraries, I try to encode: Explicitness over magic. I would rather make users type more than hide behavior behind conventions they have to discover. Composition over inheritance. Small pieces that combine flexibly beat deep class hierarchies. Clarity over cleverness. Code should be obvious, not impressive. Safety by default. The easy path should be the safe path. Why This Matters Your API is a value statement. It says what you think is important, what you think is dangerous, and how you think about the problem domain. This is why I spend so long on interface design. The APIs we create shape future thought. They outlast the code that implements them, because the patterns they teach persist in the minds of the people wh