APIs make a useful promise

An API lets one piece of software make a request of another without knowing how its internals work. Its lasting value is that separation: the website can ask for a reservation while the scheduling service handles the rules.

But “the request failed” is often less certain than it sounds. The reservation may have been created just before the connection disappeared. A dependable API defines how callers can distinguish an unwanted duplicate from work that never happened.

Define what the caller can rely on

Suppose a partner receives “accepted” after submitting an order. Does that mean the data arrived, inventory was reserved or fulfillment is guaranteed? Each interpretation creates a different obligation. The response needs to communicate the level of commitment actually made.

This is the business contract inside the technical one. Field names and documentation matter, but so do timing, authority and the meaning of success. A well-formed response can still produce a bad decision if the caller assumes more than it promises.

Begin with the action the other system needs to take next. That reveals what information and certainty it needs from this one. “Expose all our data” is a much less useful starting point than “let a partner know whether it can promise this delivery.”

Decide what a request means

Consider the difference between receiving a request and completing the work. If processing takes time, the caller may need an acknowledgment and a way to check progress. If a request is rejected, the response should help the caller correct it rather than leave them guessing.

Repeated requests deserve explicit design. A network timeout can leave a caller uncertain whether an action completed. Retrying must not accidentally create a second order or charge. Stripe’s idempotent-request documentation provides a concrete example of how an API can support safe retries. The exact behavior is specific to each provider and operation; it should be verified rather than assumed.

Set access around responsibility

Determine who can read, create, update or delete each kind of information. A reporting integration may need read access without permission to change records. A partner should not receive a wider view merely because that is easier to implement initially.

Credentials need an owner, a storage method and a replacement process. Agree how access is removed when a relationship ends. Logs should help diagnose use without unnecessarily exposing sensitive information.

Plan for change before there are dependents

Once another application relies on an API, changing it becomes a coordination problem. Identify who uses it and how they will learn about changes. Test important callers against proposed updates. Document which behaviors are stable and which are experimental.

A version number alone does not provide compatibility. The team needs a policy for replacing fields, changing rules and retiring old behavior. Keep that policy proportional to the audience: one internal caller and a public partner network have different requirements.

Questions worth settling

• Who will use the API, and what business action will each request perform?

• What happens when a request is repeated, late or incomplete?

• Which information is authoritative, and who may change it?

• How will callers test their integration before using real records?

• Who investigates failures and maintains the agreement after launch?

For a broader business view, read integrations. For operating the connection, read failure and recovery and change control.