API and integration development

Two systems that were never designed for each other meet at a seam, and nobody owns the seam.

A specification describes the happy path, because the happy path is the part both teams already agree about. What it rarely describes is the timeout, the duplicate delivery, the partial success, or the response that arrives with a 200 status and a failure buried in the body.

Those are the states an integration spends most of its life in.

The work is not the call. The work is everything that happens when the call misbehaves.

Most people who ask for this already have both systems running. What they do not have is a reliable answer to what happened to the order placed while the payment provider was restarting, or why one customer received two confirmation messages and another received none.

The first constraint predates the project. Nothing runs on a server that must be kept alive, so the integration lives in the project's own backend where there is one and in a small edge function where there is not.

A secret never reaches the browser.

Anything holding a key runs on the server side of that line, and the line is drawn once rather than argued about per endpoint.

The second constraint comes from the other system. Its rate limits, its quotas and its maintenance windows are facts to design around, and the integration that survives is the one treating a 429 as an expected state rather than an incident.

A third gets skipped more often than either. An API is a promise about a shape. Once somebody else depends on it the shape stops being yours to change quietly, and versioning is what buys back the right to change it at all.

What an engagement of this shape covers is the same list, project to project.

REST or GraphQL, versioned and documented. Authentication, rate limiting and quotas. Retries, backoff and idempotency.

A contract both sides can validate against. And machine-readable documentation an agent can consume, because whatever reads your API next is as likely to be a program as a person.

Idempotency is the one worth explaining. Every write carries a key, and a repeated request with the same key returns the first result rather than doing the work twice, which is what makes a retry safe to attempt at all.

Without it a retry is a coin flip with somebody's money on it.

The contract saves the most argument. One schema, checked by the client before it sends and by the server before it trusts, so a mismatch is caught at the boundary and named there rather than surfacing days later as a blank screen.

Rate limiting is the deliverable people assume is optional. It is what stops one consumer, or one loop somebody left running overnight, from spending the quota everybody else is sharing.

FilesHub is the API published on this site and it has its own page here. I am Ahsan Mahmood and I wrote both sides of it. That is the only reason I know how much of this work sits below the endpoint list.

The honest version is more code than the hopeful one. A naive integration is a function call.

This one is a function call, a key, somewhere to store the key, a policy for how long to keep it, and a decision about what a partial success means to your business rather than to the API. That last decision is yours.

Retries make a bad day slower rather than louder, which is the right trade and rarely feels like it while you are waiting.

A versioned contract means the old version keeps working after the new one arrives, so a deprecation becomes a date you commit to rather than a switch you flip.

There is a documentation cost nobody budgets. Machine-readable docs are generated from the same definition the server runs, because a hand-written page describing an endpoint is a second source of truth and it goes wrong quickly.

None of this is glamorous work. It is the difference between an integration that is finished and one that has only been demonstrated.

The exclusions do not change from service to service. Visual design as a standalone deliverable. Native iOS. Blockchain work. Copywriting and content.

One more belongs to this service in particular. The other system's uptime, rate limits and deprecation schedule sit outside anything I can promise you. An integration is only ever as available as the least available thing inside it, which is a sentence worth having in the contract rather than in a post-mortem.

Third-party subscriptions are yours, and so is any quota the other system meters. Thirty days of bug fixes at no charge, and after that nothing is automatic.

What no contract covers is the day the other system changes without telling either of us.