エンドポイントを書くのをやめ、システムを定義し始めよう

For a long time, I thought building APIs meant writing endpoints. You know the pattern: Define a route Validate input Query the database Transform the result Send a response Do that over and over again. Different routes. Same structure. The Illusion of Control Writing endpoints feels productive. You’re in control of everything: The logic The validation The data flow But after a while, something becomes obvious: You’re not building systems. You’re repeating patterns. The Real Problem Most APIs look like this: app . get ( ' /users/:id ' , async ( req , res ) => { const id = req . params . id ; if ( ! id ) { return res . status ( 400 ). json ({ error : ' Missing id ' }); } const user = await db . users . findById ( id ); if ( ! user ) { return res . status ( 404 ). json ({ error : ' Not found ' }); } return res . json ( user ); }); Now multiply that by: Dozens of endpoints Multiple resources Different validation rules Slight variations in logic You end up with: Repeated code Inconsistent patterns Hard-to-maintain systems You’re Not Writing Logic. You’re Rewriting Structure. Look closer at most endpoints. They follow the same shape: Extract input Validate input Execute query Handle errors Return response The structure doesn’t change. Only the details do. So why are we rewriting the structure every time? The Shift: Define, Don’t Rewrite Instead of writing endpoints… Define them. What if your API looked like this instead? get : user : GetUserById : input : id : number where : id : $param.id response : id : number name : string email : string No route handler. No repeated boilerplate. Just a definition. What This Changes When you define systems instead of writing endpoints: Structure becomes consistent Validation becomes automatic Queries become predictable Behavior becomes visible You’re no longer guessing how something works. You can read it directly. From Endpoints to Systems Traditional approach: Every endpoint is custom Logic is scattered Behavior is implicit System-driven approach: Endpoints follow a pattern Logic is structured Behavior is explicit You move from “code-first” to “contract-first.” Where the Code Goes This doesn’t eliminate code. It moves it. Instead of writing endpoint logic repeatedly… You write: A compiler that reads definitions A pipeline that executes them A system that enforces rules Code becomes the engine. Not the repetition. Example Flow With a system-driven approach, a request might flow like this: Request → Parse Definition → Validate → Build Query → Execute → Format Response The difference is: The flow is constant The behavior is defined in configuration Why This Matters Without this approach: Every developer writes endpoints differently Bugs are repeated across routes Refactoring becomes painful With this approach: Patterns are enforced Behavior is predictable Systems scale cleanly “Isn’t This Less Flexible?” Yes. And that’s the point. Unlimited flexibility leads to: Inconsistency Complexity Fragile systems Constraints lead to: Clarity Stability Speed Where This Fits This kind of system works best when: You have repeated CRUD patterns You want consistent APIs You care about long-term maintainability It doesn’t replace every use case. But it replaces most of the boring, repetitive ones. The Bigger Idea This isn’t just about APIs. It’s about how we build software. Instead of: Writing everything manually Repeating patterns Hoping for consistency We can: Define systems Enforce structure Let the engine handle execution Final Thought Writing endpoints feels like control. But it’s often just repetition. Defining systems feels restrictive at first. But it leads to something better: Clarity. Consistency. Scalability. That’s why I stopped writing endpoints… …and started defining systems. For a long time, I thought building APIs meant writing endpoints. You know the pattern: Define a route Validate input Query the database Transform the result Send a response Do that over and over again. Different routes. Same structure. The Illusion of Control Writing endpoints feels productive. You’re in control of everything: The logic The validation The data flow But after a while, something becomes obvious: You’re not building systems. You’re repeating patterns. The Real Problem Most APIs look like this: app . get ( ' /users/:id ' , async ( req , res ) => { const id = req . params . id ; if ( ! id ) { return res . status ( 400 ). json ({ error : ' Missing id ' }); } const user = await db . users . findById ( id ); if ( ! user ) { return res . status ( 404 ). json ({ error : ' Not found ' }); } return res . json ( user ); }); Now multiply that by: Dozens of endpoints Multiple resources Different validation rules Slight variations in logic You end up with: Repeated code Inconsistent patterns Hard-to-maintain systems You’re Not Writing Logic. You’re Rewriting Structure. Look closer at most endpoints. They follow the same shape: Extract input Validate input Execute query Handle errors Return response The structure doesn’t change. Only the details do. So why are we rewriting the structure every time? The Shift: Define, Don’t Rewrite Instead of writing endpoints… Define them. What if your API looked like this instead? get : user : GetUserById : input : id : number where : id : $param.id response : id : number name : string email : string No route handler. No repeated boilerplate. Just a definition. What This Changes When you define systems instead of writing endpoints: Structure becomes consistent Validation becomes automatic Queries become predictable Behavior becomes visible You’re no longer guessing how something works. You can read it directly. From Endpoints to Systems Traditional approach: Every endpoint is custom Logic is scattered Behavior is implicit System-driven approach: Endpoints follow a pattern Logic is structured Behavior is explicit You move from “code-first” to “contract-first.” Where the Code Goes This doesn’t eliminate code. It moves it. Instead of writing endpoint logic repeatedly… You write: A compiler that reads definitions A pipeline that executes them A system that enforces rules Code becomes the engine. Not the repetition. Example Flow With a system-driven approach, a request might flow like this: Request → Parse Definition → Validate → Build Query → Execute → Format Response The difference is: The flow is constant The behavior is defined in configuration Why This Matters Without this approach: Every developer writes endpoints differently Bugs are repeated across routes Refactoring becomes painful With this approach: Patterns are enforced Behavior is predictable Systems scale cleanly “Isn’t This Less Flexible?” Yes. And that’s the point. Unlimited flexibility leads to: Inconsistency Complexity Fragile systems Constraints lead to: Clarity Stability Speed Where This Fits This kind of system works best when: You have repeated CRUD patterns You want consistent APIs You care about long-term maintainability It doesn’t replace every use case. But it replaces most of the boring, repetitive ones. The Bigger Idea This isn’t just about APIs. It’s about how we build software. Instead of: Writing everything manually Repeating patterns Hoping for consistency We can: Define systems Enforce structure Let the engine handle execution Final Thought Writing endpoints feels like control. But it’s often just repetition. Defining systems feels restrictive at first. But it leads to something better: Clarity. Consistency. Scalability. That’s why I stopped writing endpoints… …and started defining systems.