An API for your own business, before anyone asks

You build an API before anyone asks because it turns business rules into a stable contract: one endpoint your website, mobile app, partner and internal tool all call, instead of four copies of the same logic. The work is small while the system is young, and expensive once three clients already depend on it.

Key Takeaways

• An API is a contract, not a product. It lets your website, app, partner and internal tools share one set of rules.
• Build it while there is one consumer. Retrofitting onto three clients means changing behaviour someone already depends on.
• Design from the domain model, not the framework. Endpoints built around your nouns survive a rewrite; endpoints built around screens do not.
• Versioning, authentication, pagination and error shape are day-one decisions, not hardening you bolt on later.
• Operate it like a service: logs, metrics, a health endpoint and a named owner. An unmonitored API fails quietly.
• An API is not always right. One partner and low volume is a nightly CSV, and that is a perfectly good answer.
• Cost is mostly engineering attention, not compute, until a chatty consumer turns bandwidth and database reads into the bill.

What does it mean to build an API for your own business?

An API is a written contract that lets other software call your business logic without knowing how it is stored. Instead of your mobile app querying the orders table directly, it asks an endpoint for an order and gets back a fixed shape of JSON. Storage, framework and hosting can then change without breaking callers.

Why build an API before anyone asks for one?

The cheapest moment to design an API is while it has exactly one consumer. You can rename fields, change pagination and fix your error format without a migration conversation. Wait until a partner, a mobile app and an internal tool all depend on you, and every change becomes a negotiation with three calendars.

There is a second reason, and it is the one that usually bites. When you build the API first, the business rules live in one place. When you build it last, they live in your web app, a spreadsheet someone emails around, and a mobile client that has been out of date since March. Finding out which of the three is correct becomes a meeting, not a query.

When do you actually need an API, and when is it overkill?

You need one when two or more pieces of software must share the same rules, or when an outside party must read or write your data on their own schedule. You do not need one when a single website is the only consumer, or when one partner simply wants a file once a day.

Portal work is the classic middle case. If you are weighing up whether customers should log in and see their own orders, that decision drives whether an API exists at all — the business case for a customer portal is really a question about shared data.

How does an API work in production?

A request arrives at your reverse proxy, which terminates TLS and forwards it to the application. Middleware checks the API key or token, then the route handler validates input, queries Postgres or Redis, and serialises a response. Every hop writes a trace, a log line and a latency metric, which is how you find the slow one later.

Two details separate an API that ages well from one that does not. The first is a request ID: generate it at the proxy, put it in every log line, and return it in a response header, so a partner's screenshot of an error leads you straight to the trace. The second is keeping the contract thin — handlers call the same service code your web app uses, rather than a second copy of the rules written for machines.

How do you build one, step by step?

Start with the nouns, not the framework. Write down the five or six things your business actually manages — orders, invoices, shipments, tickets — then define the operations on each. Only after that do you pick the HTTP verbs, the response shape and the library that renders it.

1. Map the domain. List the entities, who owns each one, and which operations are allowed. This is a whiteboard exercise, not a coding one.
2. Write the contract first. Describe the endpoints in OpenAPI before you implement them. It forces the naming argument into week one instead of month six.
3. Choose the transport and version scheme. Put the version in the URL path, because it shows up in logs and in a partner's error report.
4. Build handlers over shared service code. The web app and the API must call the same functions, or the rules drift within two sprints.
5. Add authentication and authorisation. Tokens or signed requests, scoped per client, authorised per object rather than per route.
6. Add pagination, filtering and rate limits. Cap page size on the server. Assume someone will eventually ask for everything at once.
7. Instrument it. Structured logs with the request ID, latency and error-rate metrics, distributed traces, and a health endpoint your uptime check can hit.
8. Hand a staging URL to a real consumer. Someone outside your team integrates using only the documentation. Their questions are your bug list.

Which configuration decisions matter most?

Versioning, pagination, idempotency and error shape are the four that cause the most pain later. Put the version in the URL path so it is visible in logs. Cap page size server-side, because a client that asks for everything will eventually ask for everything at once. Accept an idempotency key on any write.

Pagination deserves its own paragraph. Offset pagination is simple and fine on small tables, but it drifts when rows are inserted while a client is paging through. Cursor pagination — usually a timestamp plus an ID, encoded — stays stable and is cheaper on large tables. Whichever you pick, publish the maximum page size and enforce it.

How do you verify the API works before a partner integrates?

Test the contract, not just the happy path. Keep a collection of requests that asserts status codes and response bodies, run it in CI on every commit, and treat a schema change as a breaking change unless you have proven otherwise. Then have someone outside your team integrate against the staging URL using only the documentation.

curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/orders?limit=20

What breaks in production, and how do you debug it?

The failures you will actually see are 401s from an expired token, 429s from a client ignoring rate limits, and slow queries hidden behind a healthy 200. Work outward: check the proxy log for the status code, the trace for the slow span, then the database for the query plan. Never start by restarting the app.

A stable error format is what makes that debugging possible. If every failure returns a shape like this, a partner can tell you exactly what happened without a support call:

{
  "error": "validation_failed",
  "field": "due_date",
  "request_id": "01HQ8Z..."
}

1. Confirm the status code and the request ID in the proxy log.
2. Pull the trace and find which span owns the latency.
3. Check the database for a missing index or a lock wait.
4. Check whether the caller changed behaviour before you changed anything.

What does it cost to run, in money and attention?

Compute is rarely the big number. The recurring cost is engineering attention: rotating credentials, answering partner questions, watching error rates and deciding when a v2 is worth it. Egress bandwidth, managed gateway fees and database read load scale with traffic, so check the vendor's own calculator before you commit to a design.

Monitoring has a cost too, and it is easy to miss. Log volume grows with request volume, and a verbose debug level left on over a long weekend can cost more than the instances serving the traffic. Decide retention up front: full logs for a fortnight, aggregates for a year.

What are the security considerations?

Treat every caller as untrusted, including the mobile app you wrote. Authenticate with short-lived tokens or signed requests, authorise per object rather than per route, and never trust an ID sent by the client. Log authentication failures and rate-limit by identity, not just by IP, because shared NAT means one office can lock out everyone.

One practical warning: a static key shipped inside a mobile app or a browser bundle is not a secret. Anyone can extract it. Your app should authenticate to your backend, and that backend holds the key. If you are unsure how your current setup handles this, our FAQs cover the common patterns.

Which mistakes do teams make most often?

The same three show up repeatedly: exposing database rows directly, so a schema change breaks every client; skipping pagination until the table is large; and shipping without a documented error format, so partners retry a request that will never succeed. Each one is cheap to fix in week one and expensive in month twelve.

Is an API always right? How do the alternatives compare?

Sometimes a scheduled file is better. A nightly CSV over SFTP has no auth flow to rotate, no rate limit to tune and no on-call surface. Webhooks beat polling when you must push events. Pick the integration with the fewest moving parts that still meets the partner's actual latency requirement.

Option	Best when	Operational overhead
REST API	Several consumers share the same rules	Auth, versioning, monitoring, docs
Webhooks	Events must reach a partner immediately	Retries, signing, delivery visibility
Message queue	Consumers can be offline and catch up later	Broker to run, dead-letter handling
Scheduled CSV	One partner, low volume, daily is enough	Almost none beyond a job that alerts on failure

What does this look like in a real business?

Picture a mid-sized distributor in Kathmandu running orders through a custom web app and a separate accounts package. Stock numbers disagreed weekly, and someone reconciled them by hand every Friday. A small read/write API over the order tables gave the accounts package a nightly sync and the mobile sales app the same endpoints. Reconciliation stopped being a job.

The trade-off was real: the API needed an owner, a token rotation routine and monitoring. That is roughly the same shape of work behind the analytics platform we built for a research and analytics institute — one contract, several consumers, and a clear owner.

If you are deciding whether this is worth doing in-house, the comparison between custom software and off-the-shelf tools is the same argument in a different costume. For most of the businesses we talk to, the answer is a small API built early, plus custom software development to keep it honest.

In short

• Build the API while one consumer exists, not after three.
• Write the contract before the code; let the domain drive the endpoints.
• Version, paginate, authenticate and log on day one.
• Watch it like a service with an owner, not a script that runs somewhere.
• If a nightly file solves it, ship the nightly file.

People also search for

• Do we need a customer portal or just a login page?
• What should a web development quote actually include?
• Which accounts should the business own?
• Should we rebuild the system or refactor it?
• How do we stop feature creep before launch?
• Is a headless CMS worth it for a business site?
• Questions to ask before approving a web proposal

If two systems in your business already disagree about the same numbers, an API is usually the cheapest way to stop that. Our team can help you scope it, build it in your own accounts and repositories, and hand over something your own developers can operate. Tell us what you are trying to connect, or look at the wider services we run.