API Design for Backend Systems

Sun, 26 Jul 2026 19:00:00 +0530

A few weeks ago I designed Relay, a multi-tenant AI API gateway, as a system design exercise. That post covered the database, the auth, the billing. It did not cover the thing every one of those systems is sitting behind: the API itself.

Here is the question that post left open. When someone builds GET /v1/requests to list a tenant’s API call history, what should that endpoint actually look like? Offset or cursor pagination? What does the response envelope contain? What happens when Relay needs to add a filter that does not fit in a query string? What does a webhook payload look like when Relay tells a tenant “your batch job finished”? None of that is specific to AI gateways. It is the same decisions every backend API makes, made badly often enough that “REST API” has become a phrase that means “JSON over HTTP, structure unspecified.”

Http on Lorbic

API Design for Backend Systems