APIs Built for Real Products
Doris Infotech
Users never see your database schema. They see whether a screen loads, a payment completes, or a form comes back with a useful error. That path runs through the API. If the contract is vague, every client invents its own meaning - and the product starts to drift.
At Doris Infotech we treat APIs as a product surface, not a dump of internal tables. Resources have names people can reason about. Status codes mean what they say. Breaking changes are rare, announced, and versioned.
The goal is not a larger OpenAPI file. The goal is a backend other teams can build against for months without a Slack thread for every field.
Model the product, not the tables
An endpoint named after a join table is already leaking storage into the product. Expose the thing the user cares about: an order, a vacancy, a subscription. Nest only when the child cannot exist without the parent. Query params filter and paginate; they should not become a second undocumented language.
Errors should tell the next screen what to do
A 500 with an empty body forces the UI to guess. Return a stable code, a short message the user can see, and enough detail for logs. Validation failures belong on 400 with field names. Auth failures belong on 401 and 403, not a generic crash. Honest errors are how support tickets stay small.
Version change. Do not surprise clients.
Adding an optional field is usually safe. Renaming or removing one is not. Prefer additive change. When you must break a contract, ship a new version and keep the old path long enough for apps and partners to move. A changelog in the repo is cheaper than a silent production incident.
Paginate, cache, and keep payloads lean
List endpoints without limits will fail the first time a table grows. Use cursor or page parameters from day one. Cache what is public and slow to compute. Do not send ten nested objects when the card needs four fields. Backend performance is often just refusing to over-fetch.
Document the contract where engineers work
OpenAPI, a shared types package, or example requests in the README beat a slide deck. If frontend and mobile cannot generate or copy a working call, they will hard-code assumptions. We keep the contract next to the code so reviews catch drift before it ships.
