标签：#apidesign

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