A product built from small APIs is easier to reason about than one large integration. A single integration that validates an email, geolocates an IP, generates a QR code and fetches exchange rates sounds convenient. One base URL, one client, one place to look. It also fails in several unrelated ways, and each failure is harder to diagnose because the surface is larger.
We build small APIs instead. Each endpoint does one job, has a short parameter list and returns a shape that does not change when a new feature appears. That choice costs us more pages and more documentation. It saves time when something breaks.
Why small APIs keep one job per contract
Small APIs start with a narrow contract. Take IP Geolocation. It accepts an IP address, an optional format and a flag for the full response. The output is a country code, or a larger object with city, region and coordinates. A client can cache that response for a day and forget about it.
The email checker looks nothing like it. It asks a mail server whether a mailbox exists and can return unknown when the server refuses to answer. Putting both behind one endpoint would force a shared response envelope and a shared error model. The email case would inherit assumptions that only make sense for geolocation.
We keep new behaviour in new parameters or new endpoints. When the exchange-rate data needed a base and quote conversion, we added base and quote to Exchange rate. Existing clients kept the table response they already parsed.
Testing gets smaller
A small endpoint has a small test matrix. For the QR generator we check a short string, a long URL, an invalid size and a missing data parameter. That is enough to catch the common failures. A combined endpoint would need combinations of those cases across every feature.
Fixtures stay readable too. A JSON response with five fields is easy to compare. A response with nested objects for five services is not. When a test fails, the failing field usually points to the cause.
Caching and rate limits
Different endpoints have different costs. A public IP lookup takes a few milliseconds. A DNS blacklist check waits for dozens of DNS answers and can take a second. Separate endpoints let us cache and limit them separately. The cheap call can run often. The expensive one gets a lower ceiling.
That separation also protects clients. A slow WHOIS query cannot exhaust the budget for QR codes. A burst of email checks cannot make geolocation unavailable.
Replacing a dependency
Data sources change. Geo databases get new releases. A mail server changes its policy. With one endpoint per job, we can replace the source behind the contract and keep the response shape stable. The client sees the same fields.
We did that with the DNS blacklist check. The old implementation made dozens of HTTP requests to a third-party service. The current one queries DNS directly. The response still lists the zones where the address appears.
The cost
Small APIs mean more pages, more examples and a longer catalog. Discovery becomes a real problem, so the site groups APIs by category and puts the endpoint, method and parameters on every page. The tradeoff is deliberate. A developer can find the right tool and read its contract in a minute.
A large integrated product can still be the right choice for an internal system with one team and one client. For a public catalog, small contracts survive contact with different clients, budgets and failure modes.
Start with the API collection or read how we handle response formats.
Monitoring and versioning
A small API is easier to monitor than a large one. Small APIs keep each graph readable. The same small APIs that add pages to the catalog add clarity to the graph. We can track latency, error rate and cache hit rate per endpoint. When the DNS blacklist check gets slower, the graph shows it without noise from QR codes. When a new release changes the email checker, the alert points to one contract.
Versioning is simpler when small APIs own their contracts, and small APIs age better than one shared envelope. A new parameter can be added without touching other endpoints. A breaking change can live behind a new name while the old one keeps working. Clients move when they are ready. Read how we handle response formats for one example of a contract that stayed stable.
Further reading: RFC 9110, HTTP Semantics.