The Best API Design for Backend Systems at Scale
One of the biggest performance unlocks you can give yourself and your AI agents as a backend developer is better api design. If your api design is messy, everything gets harder. Debugging gets harder. Adding endpoints gets harder. Scaling gets harder. Even getting AI to work productively in your codebase gets harder.
After years of building systems across different languages, runtimes, and frameworks, I have found a simple approach to api design that works extremely well whether you have 5 APIs or 5,000. This is the same structure we use in production to serve thousands of requests per second, and it holds up for debugging, maintainability, and clean growth.
The core point is simple. You do not need to build your backend around whatever framework is currently fashionable. GraphQL, tRPC, Express, and a dozen other tools are often pushed because they are popular, not because they are necessary. If you get the foundation right, your api design can stay framework agnostic and far more under your control.
The core job of an API endpoint
At a high level, every request starts with a client sending data to your backend. Once that request arrives, your backend really only needs to do a few things:
* Figure out which API is being called
* Rate limit the request
* Validate the input
* Run the handler
* Return a response
That is the backbone of good api design. Every endpoint should clearly define:
* How the endpoint is located
* What rate limits apply
* How input is validated
* What code actually runs
* What output shape is returned
This approach is not tied to a specific stack. You can do it in TypeScript, Go, Rust, Java, C++, or anything else. The principles stay the same.
Why framework first thinking causes problems
A lot of teams start backend work by choosing a framework and then shaping the system around its defaults. That is backwards.
Your startup infrastructure should be built around control, clarity, and scalability. If your framework makes routing, validation, response handling, or debugging feel magical, that magic often becomes friction later. The more custom behavior your product needs, the more valuable it is to own the request lifecycle yourself.
That is the real advantage of this api design style. You stay fully in control of how requests are parsed, how errors are shaped, how auth is enforced, and how endpoints are organized.
A practical request flow that scales
Before rate limiting or validation, the backend needs to determine where the request should go. In our case, the client sends two key pieces of information in the request body:
* namespace
* API name
The namespace is mostly for organization. You could survive without it, but it helps group APIs cleanly. For example, you might have a public namespace and keep related functions there. There is no magical security property in the namespace itself. It is mainly a categorization layer, though you can attach custom behavior to it if you want.
Once the backend knows the namespace and function name, it can resolve the correct endpoint and apply the rest of the pipeline in a predictable order.
The order matters
A request should typically move through the system in this order:
1. Resolve the target API from the payload
2. Apply rate limiting
3. Validate the request data
4. Run the handler
5. Perform auth checks inside the handler path where appropriate
This ordering is deliberate. Validation is often cheaper than auth. If auth requires a database lookup, there is no reason to do that work before confirming the payload even makes sense. A clean api design saves resources by failing cheap and early.
Why we standardize on POST for everything
This is one of those decisions that some people will disagree with, but it has been extremely effective for us.
We standardize backend communication around POST requests, even for operations that many teams would label as GET. That means reads and writes both come through the same method.
Why?
* GET requests have special behavior in many environments
* GET requests do not support a request body in the same way
* Reverse proxies may treat methods differently
* Caching behavior can become inconsistent or surprising
* Clients become more complex when method behavior varies per endpoint
By standardizing on POST, the backend contract becomes simpler. The client always knows how to communicate. The infrastructure does not need to juggle method-specific assumptions. And the request payload structure can remain consistent across the board.
That kind of consistency is underrated in api design.
Why we return 200 for application-level errors
This is another deliberate choice.
As long as a request reaches our infrastructure, gets parsed successfully, and the backend processes it, we return HTTP 200. The actual success or failure of the operation is encoded in the JSON response body.
In practice, that means the response follows a stable schema like this conceptually:
* status: okay or error
* error message: always a string when present
* output: the actual result payload when successful
So if the request reached our backend and our backend handled it, the transport layer says 200. If Cloudflare is down or our infrastructure is unreachable, that is when you would see a true transport or infrastructure level failure such as a 500 class response.
This creates a clean distinction:
* HTTP status tells you whether the request reached and was processed by the backend infrastructure
* JSON status tells you whether the application logic succeeded
You can disagree with this style, but it makes the client contract very stable. And stable contracts are a huge win in api design.
Try Requestly for API testing and debugging
Organize API collections, test requests, and intercept responses with the same tool we use to manage backend workflows.
Using namespaces to keep APIs organized
We organize APIs by namespace and function name. For example, one function might live under a public namespace and be named getUserId.
That means the client payload includes enough information for the backend to route the request without relying on a sprawling path structure or a framework-specific router hierarchy.
This keeps endpoint discovery predictable and lets you build tooling around your api design more easily. It also makes things nicer for AI agents, because they can reason about a simple, repeatable layout instead of crawling through a tangled routing system.
The folder structure that keeps everything sane
In our backend monorepo, the API package contains a folder per namespace, and inside that namespace each endpoint has its own directory.
Each function generally has two required files:
* constants.ts
* run.ts
It may also have an optional test file:
* test.spec.ts
What goes into constants.ts
This file defines the metadata and schema contract for the function. That usually includes:
* Input schema
* Output schema
* Rate limit configuration
* Optional public metadata for generated OpenAPI docs
In TypeScript, we use Zod for validation. The input schema defines exactly what payload the endpoint accepts. The output schema defines exactly what it returns.
That matters for two reasons:
1. Type safety becomes far better
2. Consistency across endpoints becomes enforceable
You can validate things like:
* Email format
* Username rules
* Minimum and maximum lengths
* Conditional shapes
* Required versus optional fields
And this is not just decorative metadata. The schema is executed at runtime. It is part of the actual request validation path, so it needs to be designed carefully.
What goes into run.ts
This is the actual handler logic. By the time execution reaches run.ts, the request has already survived routing, rate limiting, and validation.
That keeps the business logic small and focused.
This is also the right place for function-level auth enforcement. Some endpoints may require access checks. Others may not. By keeping auth policy close to the function, you avoid pretending that everything in a namespace has identical access rules.
That flexibility is another sign of solid api design. You want the structure to be standardized, not rigid in the wrong places.
How rate limiting works cleanly
Every endpoint can define its own rate limit settings, such as maximum requests per window and the duration of that window.
For example:
* 60 requests
* per 1 minute window
The implementation details can vary. You might use Redis. You might use Postgres. The storage choice is less important than the contract.
In our case, rate limiting is custom:
* If the request is unauthenticated, rate limiting applies by IP address
* If the request is authenticated, rate limiting applies by user account
That gives you better behavior across public and private access patterns while keeping the endpoint-level configuration simple.
Why strict output schemas matter
A lot of teams focus on input validation and get lazy with output validation. That is a mistake.
If your endpoint can return inconsistent shapes, the client becomes brittle, debugging gets painful, and typed tooling starts to lose value. A mature api design validates both directions.
Once input and output schemas are standardized, most of the endpoint boilerplate becomes templated. The only truly custom work is:
* The input definition
* The output definition
* The actual handler logic
* The endpoint-specific rate limit and auth choices
Everything else can be generated or enforced automatically.
Testing and debugging become much easier
Once APIs follow a stable structure, testing gets simpler too.
We keep optional test.spec.ts files alongside endpoints so handlers can run locally and in CI. These can be unit tests, functionality checks, or endpoint-level behavior tests.
For API exploration and debugging, we use Requestly. It is useful for a few reasons:
* You can organize API requests into collections
* You can test and debug real endpoints quickly
* You can experiment with methods and payloads
* The workspace is Git friendly because it is backed by JSON files
* It can sit inside your repository and sync with your team easily
* It can intercept and modify HTTP requests and responses
That last point is particularly useful when working locally. If you want to keep using production infrastructure but simulate a specific response, you can intercept only the parts you care about instead of spinning up a full local replica.
The request envelope should be standardized
One important implementation detail is that every API request should follow a common envelope schema. Even if each endpoint has its own data payload, the outer request shape should stay predictable.
In our setup, the request envelope includes fields like:
* Namespace
* Function name
* Auth token or API key when needed
* Data payload specific to the endpoint
The backend first parses this common request envelope. Since the backend already knows how to validate the envelope, it can then hand off the inner data field to the target endpoint's schema validator.
That separation is clean, scalable, and easy to reason about.
Why this structure works so well with AI agents
One of the more underrated benefits of this api design is how well it works with AI-assisted development.
If an AI agent needs to create a new API endpoint, the task is very bounded:
1. Create a folder in the correct namespace
2. Add constants.ts
3. Add run.ts
4. Optionally add test.spec.ts
That is it.
The agent does not need to absorb a huge amount of routing context, framework conventions, or hidden middleware behavior. It only needs to understand the small, repeatable contract of a single endpoint.
That reduction in context load is a massive operational benefit. Good api design is not just about computers. It is about making systems easier for humans and tools to work with.
This approach is language agnostic
Although the implementation discussed here uses TypeScript, Node.js, and Zod, the pattern itself is not tied to that stack.
You can apply the same model in:
* Go
* Rust
* Java
* C
* C++
* Pretty much any language that lets you parse requests and dispatch handlers
All you need is one thin layer that:
* Accepts the incoming request
* Parses the common request payload
* Finds the right namespace and function
* Applies shared checks
* Invokes the target handler
Once that layer exists, the rest of the system becomes a repeatable pattern.
The real takeaway
The best api design is not the one with the most hype around it. It is the one that keeps your backend predictable, scalable, debuggable, and easy to extend.
If you standardize the request lifecycle, define clear schemas, keep handlers isolated, and organize endpoints by namespace and function, you end up with a backend that scales smoothly from a handful of APIs to thousands.
And once that foundation is in place, adding a new endpoint stops feeling like infrastructure work. It becomes a small, controlled change with very little overhead.
That is what good api design should do.