API and integration development — services — Ahsan Mahmood
Typed, versioned HTTP APIs and the third-party integrations around them.
The layer between two systems that were not designed for each other — including the failure modes nobody specifies.
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.
from $800
How long it takes
Small features 1–2 weeks, an MVP 4–8 weeks, a full production app 8–16 weeks. Those are ranges I have hit on work of that shape before. The scoping call settles how many failure paths the integration has to handle, because that list is longer than the endpoint list and it is where the work actually goes.
Every engagement of this shape covers
- REST or GraphQL, versioned and documented
- Authentication, rate limiting and quotas
- Retries, backoff and idempotency
- A contract two sides can both validate against
- Machine-readable docs an agent can consume
Built with
- Node
- Cloudflare Workers
- REST
What do you mean by the failure modes nobody specifies?
The timeout, the duplicate delivery, the partial success, and the response that returns a 200 status with a failure inside the body. Those are the states an integration spends most of its life in, and a specification usually describes the happy path instead. Retries, backoff and idempotency are part of every engagement of this shape for exactly that reason.
REST or GraphQL?
Whichever the consumers argue for, decided on the scoping call and documented either way. REST suits a small number of well-known resources. GraphQL suits many consumers who each want a different slice of the same data. Both are versioned, both are authenticated and rate limited, and both ship with machine-readable docs.
My product has no backend of its own. Can it still have an integration?
Yes, and it is the common case here. The server-side piece is a small edge function on the platform the project already uses rather than a server somebody has to keep alive, and it exists so the key, the retry state and the idempotency record have somewhere to live that is not the browser. That is a few files, not an infrastructure decision.
Can my team build against this while you are still working on it?
Yes, because the contract is a schema both sides validate against rather than a document one side wrote. The client checks before it sends and the server checks before it trusts, so a mismatch is named at the boundary instead of arriving later as a bug report about a blank screen.
How much does an API or integration project cost?
$800 USD is the floor for a small, well-defined feature. Everything above that comes from a scoping call, in writing, before any work starts. What moves the number here is how many failure paths the integration has to handle and how well the other system is documented, because an undocumented endpoint is discovered by calling it.
https://aoneahsan.com/services/api-and-integration-development