API Development
Documented, versioned APIs for web applications, apps and connected systems — the foundation the rest of your system landscape builds on.
Risks we catch early.
What typically goes wrong in systems like this — and how we prevent it before it shows up in production.
- 01
Silent breaking change
- Why
- A renamed field or a validation rule tightened after the fact looks like a fix. For the third-party code on the other end, it is a break — no matter how small the change appears.
- Early warning signs
- Changes to existing behavior instead of additive extensions; no automated test against the public contract; callers report the error before your own monitoring does.
- How we prevent it
- Extend additively wherever possible. The public contract is tested automatically before rollout; if a new version becomes necessary, the old one remains valid and untouched.
- Trade-off
- Cost: contract tests and restraint when changing what exists. Different when: the API is purely internal and deployed together with its callers — then the contract is cheap to change.
- 02
Errors without a contract
- Why
- Errors are part of the contract, not an edge case next to it. Changing free text forces callers to check for wording — and turns the message itself into the contract.
- Early warning signs
- No stable, classified code; client and server errors cannot be told apart, so nobody knows whether to retry or correct; internal details in messages.
- How we prevent it
- Stable, machine-readable error codes, a clear distinction between caller errors and provider errors, and no internal traces in the response.
- Trade-off
- Cost: another contract surface maintained with the same care as the success responses. Different when: an internal API with a single consumer that evolves alongside it — there, the error model can stay leaner.
- 03
Confusing the interface with the implementation
- Why
- The provider behind an interface is replaceable; the data that has flowed through it and stayed is not. If you tie your own view to a provider’s shape, you will feel every switch all the way down into your existing data.
- Early warning signs
- Your own data model follows the structure of an external service; a provider switch is planned as a connection question, not as a translation of existing data.
- How we prevent it
- The data is kept in a shape that belongs to the system; the external service sits behind a boundary that holds.
- Trade-off
- Cost: a translation layer and a verified migration of existing data instead of a direct switchover. Different when: the existing data is small and non-critical and would be cheap to obtain again.
The questions we ask before writing code.
Not advice, but decision questions. Your answers shape the architecture — not the tools.
- 01
What shape does the communication take — things, actions or flexible queries?
- Why it matters
- The style shapes the contract, and the contract is hard to change. Deciding by trend treats a question of fit as a question of taste.
- Typical consequence
- Named things lead to REST, actions between known systems to RPC, very different data slices for many callers to GraphQL. When in doubt, the most widespread style — one that will still be understood and staffable in ten years.
- 02
Does the API express the caller’s business domain — or the internal implementation?
- Why it matters
- Whatever a consumer can observe becomes the contract. Mirrored internal structures couple external systems to decisions you wanted to be free to change.
- Typical consequence
- We design the external representation separately from the internal model and translate at the boundary. For a short-lived prototype, this is unnecessary.
- 03
Does an operation change state or money?
- Why it matters
- As soon as an API is reachable over a network, the same request will eventually arrive twice. That is not a bug but a property of distributed communication.
- Typical consequence
- Then it is designed to be idempotent: a unique key per logical operation, checked and persisted in the same transaction as the effect. Reads and naturally idempotent operations don’t need this.
- 04
Could an existing caller notice the planned change?
- Why it matters
- If the answer is yes, the change is breaking — no matter how small it appears. A validation rule tightened after the fact is a break, too.
- Typical consequence
- We solve it additively wherever possible. Where not, a new version is created, the old one remains valid and untouched, and retirement follows an announced deprecation process rather than a cutoff date.
What it is — and what it includes.
An API provides the interfaces through which web applications, apps, partners and connected systems such as ERP or CRM talk to each other. Batunet designs APIs as long-lived contracts — versioned, documented and stable, so that everything else can safely build on them.
Scope of services
- API design (REST, GraphQL)
- Versioning without breaking changes
- Authentication and rate limiting
- Documentation and developer experience
- Reliable webhooks and events
How we build. The Batunet Engineering Method.
Seven phases — from the first question to operations years later. Not a project process, but the way we think.
- 01
Frame
The actual problem, its boundaries and a measurable definition of success are established before any solution is considered.
- 02
Model
The domain is modeled and sliced into contexts — with a precise, shared language.
- 03
Decide
The load-bearing decisions come first — deliberately and documented, while change is still cheap.
- 04
Prove
A walking skeleton proves the architecture on the riskiest path — before going broad.
- 05
Build
On top of the proven skeleton, the system grows in verifiable, reversible steps — with progress visible every week.
- 06
Harden
Failure cases, load and security are tested, not assumed. “It runs” becomes “it holds.”
- 07
Operate
We operate, monitor and keep evolving the system — and keep it understandable and changeable.
What you can rely on.
- 01
APIs that evolve without breaking
- 02
A stable foundation for partners and other systems
- 03
Documentation others can work with right away
When it fits — and when it doesn't.
An honest answer is part of good advice. We recommend the path that fits the problem.
Good fit
- Several callers share the same business logic — frontends, mobile apps or partners. From the second caller on, the API is a contract, not an implementation detail.
- Existing business logic needs to be made accessible in a controlled way, without coupling external systems to its internals.
- An external service should remain replaceable. A dedicated API in front of it separates what stays from what gets replaced.
- The API should grow additively over years without breaking its consumers’ production systems.
Not a fit
- Two of your own services that are developed and deployed together. There, the contract is cheap to change — tighter coupling is acceptable.
- A single consumer that evolves alongside the API and that you coordinate yourself. The full rigor of contract surface, stable error codes and a deprecation process only pays off with external callers.
- A prototype or a short-lived interface. There, directly mirroring internal structures is the faster and correct choice; decoupling pays off only when the API lives long.
Questions about API Development
REST or GraphQL?
REST for stable, cacheable resources; GraphQL when clients need very different slices of data. REST is often the right, boring choice.
How do you avoid breaking changes?
Through deliberate versioning, additive changes and clear contracts. An API is a promise to its consumers.
Continue your engineering journey.
Related concepts, decisions, playbooks and perspectives — as one connected path, not a list of links.
Let’s talk about your project.
No sales team. A direct conversation with the management.
