# APIs are contracts between parts of the business.

> An API that responds successfully is not necessarily an integration that preserves business correctness. System boundaries need ownership, failure semantics, observability and a predictable way to evolve.

Canonical URL: https://marmation.com/expertise/api-and-platform-engineering/

## The decision

If the response is lost, who knows whether the order exists?

Define state ownership, idempotency and reconciliation as part of the business contract. An HTTP success code alone cannot make two applications agree.

## The situation behind the request

Two applications disagree on whether an order was accepted, updated or canceled. A retry writes a duplicate transaction because the message broker delivered the event again.

## Where the obvious solution falls short

Without idempotency, state ownership and reconciliation, every connected service amplifies errors. An AI feature acting through these APIs adds new uncertainty unless tools are carefully scoped.

## How we would approach the work

Define domain events, ownership, schemas and recovery. Prefer stable platform capabilities and build bespoke interfaces only when integration requirements warrant them.

## What the engagement may include

- Service/API contracts and versioning policy.
- Event, queue and integration design with idempotency.
- Observability, dependency tracking, retry and reconciliation.
- Documentation, automated integration tests and release planning.

## The choices worth making explicitly

Direct API calls may be right for a small synchronous workflow. Events and queues may be required for asynchronous stateful work. Complexity should follow actual reliability needs.

## What we would test before calling it ready

Exercise schema version changes, out-of-order events, credentials rotation, repeated requests, partial outages and replay.

## A sensible first step

Start with a transaction whose success can be verified across system boundaries.

## Related reading

- [Integration is a product decision, not just an API connection.](https://marmation.com/solutions/enterprise-integration/)
- [Your systems may work. The workflow between them may not.](https://marmation.com/solutions/intelligent-business-systems/)
- [Autonomy should be earned, not assumed.](https://marmation.com/expertise/ai-agent-orchestration/)