Skip to content
Custom software

How to design an API for your application and partners

A useful API lets a partner finish their work without guessing what your application has just done. Design therefore starts with the meaning of operations and the rules of cooperation. Addresses, formats and technology follow. Here is how to prepare an interface that can be used safely, changed deliberately and handed over to another team.

How to design an API for your application and partners

Imagine a manufacturer exposing product availability and order submission to distributors. Opening existing database tables is not enough. A distributor needs to know whether availability is indicative, when stock becomes reserved and how final confirmation arrives. Without those answers, a technically correct connection can still create commercial mistakes.

This article addresses APIs you provide to other people. Our systems integration guide covers connecting existing services. The distinction is ownership: as the provider, you define the interface contract and carry the consequences of changing it later.

01Start with the partner’s task and your responsibility

Describe several complete workflows: obtain a quotation, place an order, check its status and request cancellation. Identify the input, outcome and person responsible for resolving ambiguity. A partner may need a different view from your internal application. Sales notes, procurement prices and internal employee identifiers usually have no role in completing their task.

Distinguish reading information from issuing a binding instruction. Displaying stock availability does not itself promise a reservation. Accepting a request does not necessarily mean approving an order. Explain those differences in ordinary language and review them with a future consumer before implementation. The deliverable should be shared understanding of the process, rather than a list of URLs.

02Design a stable business model instead of exposing the database

Name resources and relationships so they can survive internal restructuring. An order may contain lines, delivery information and a status without revealing every table used to construct it. Public identifiers need a defined lifetime. Decide whether migration changes them and how a consumer recognizes a record that is no longer usable.

AreaDesign decisionWhat can otherwise go wrong
Money and quantityCurrency, unit, precision and rounding rules.A partner mistakes a package for one item or assumes another currency.
TimeTime zone, format and the event represented.Dispatch date is confused with the time of the last update.
Empty valuesDifference between an absent field, null and an empty string.A partial update unintentionally clears an address.
Process stateAllowed transitions and responsibility for changing state.An accepted request is treated as a completed order.

Use the same definitions in documentation, examples and tests. When older records are involved, start with data migration preparation. Adding an API does not remove inconsistent meanings. It distributes them to partners more efficiently, which makes unresolved differences more expensive.

03Agree the interface contract before implementing it

The OpenAPI specification describes HTTP interfaces for people and tools. Capture operations, inputs, responses and security schemes. The file alone does not prove that business rules are correct or that the running service matches its description. Assign an owner, review changes and verify the implementation against it.

Give a partner the proposed contract with realistic examples prepared without exposing sensitive records. Ask them to complete one entire workflow against a test interface or simulated responses. Notice where they need an undocumented assumption. If every field requires a phone call, the design is not settled. Generated documentation should support this conversation rather than replace it.

04Treat errors and concurrent changes as normal service behaviour

A consumer needs to distinguish invalid input, insufficient permission, a conflict with current state and temporary unavailability. RFC 9457 provides a standard format for machine-readable problem information. Include a stable problem type and a safe support reference. Avoid exposing stack traces or confidential implementation details.

Two systems may update the same record. Decide how they recognize an outdated version and what happens when a conflict occurs. Conditional requests described in HTTP semantics can make a change depend on the matching resource version. The consumer then reloads current state and makes a decision instead of silently overwriting newer work.

For commands with side effects, also specify safe repetition and the lifetime of a request identifier. Explain the response when the identifier is reused with changed data. This is not a universal property that can be assumed for every operation. It must fit the business process and be demonstrated through acceptance scenarios.

05Separate a partner’s identity from permission to access data

Give each integration a traceable identity and the access it needs. A shared credential used by several businesses makes revocation and investigation harder. The server must also authorize the particular resource and permitted fields. Our API security guide explains these controls in more detail.

Separate test and production access. Agree who issues, replaces, revokes and owns credentials. Ending the commercial relationship must stop further access and any associated automated work. For the operational procedure, see secrets and configuration management. A completed onboarding checklist is not a substitute for an offboarding procedure.

Five steps from a partner’s workflow to a maintained API
Design continues after launch: interface changes require communication, verification and an accountable owner.

06Plan data volume, events and operating boundaries

Lists need pagination, stable ordering and documented behaviour when records change during retrieval. Explain whether an export represents one consistent snapshot or a changing selection. Design filters and request size limits around actual tasks. An unrestricted export is not automatically a more useful service if it makes ordinary activity unreliable.

Decide when the consumer retrieves state and when it receives a notification. An event may indicate that something changed, but the authoritative current state must remain discoverable. Document repeated delivery, ordering and history availability. For long operations, separate acceptance of work from completion and provide a traceable way to obtain the outcome.

Derive limits from operation cost and fair sharing of capacity. Request count is only one dimension: concurrency, response size and background processing matter too. Use our guide to database and API performance when locating the actual constraint. Publish limits that the service can enforce and that partners can respond to.

07Use versioning to protect real consumer behaviour

ChangeWhat to verifyHow to prepare
New optional fieldWhether the consumer tolerates unknown data.Compatibility tests and updated examples.
New order statusWhether a client assumes the status list is closed.An agreed response to an unfamiliar value.
Changed meaning or required inputWhether existing requests remain valid.A managed migration or a new interface version.
Retiring an old versionWho still uses it and who has adopted the replacement.Notification, migration evidence and a retirement plan.

A version number does not create compatibility. Track actual operation usage and agree how changes are announced, how long versions are supported and who handles incidents. Retirement should follow demonstrated migration or an explicit decision by the responsible parties. It should not be based solely on the development team wanting to remove old code.

08Prepare partners for onboarding and everyday support

Handover includes test data, a first working scenario, failure examples, access procedures and a contact point. A partner needs to identify whether a problem occurred in their system, yours or the transfer between them. A request reference connects the support discussion with operational records without requiring complete sensitive responses to be emailed around.

Observe time to the first successful workflow and recurring questions. These signals reveal design quality more usefully than the number of published operations. Give documentation and ongoing maintenance explicit ownership. Without it, an interface gradually loses credibility as the implementation and examples diverge.

Planning an API for distributors, customers or your own application? With Listify’s integrations and API services, the starting point is the workflow, data and responsibility boundary. Prepare an example partner task and a list of existing systems so the design and first verifiable phase can be scoped.

Discuss your API design

09Frequently asked questions about partner API design

Do we need an API for just one partner?

It depends on frequency, importance and the degree of automation. A controlled export may suit a one-off transfer. A recurring process with status confirmation usually needs a clearer interface. Describe the work and the cost of today’s method before choosing the mechanism.

Does OpenAPI provide complete documentation?

It provides an important machine-readable description. Add field meaning, complete workflows, limitations and change procedures. Documentation must match the deployed version, and a partner should be able to use it without relying on private assumptions.

Should public and internal APIs be identical?

Not necessarily. They can share business rules, but a partner needs a stable contract and only permitted data. Changing an internal screen should not automatically break a distributor’s integration.

Must every API use REST?

No. Establish the workflow, volume, event requirements and partner capabilities first. This article mainly addresses HTTP APIs. Another style may be appropriate when its benefits justify the additional integration and operating costs.

What should we prepare for an initial discussion?

The partner or application types, main workflows, data sources, expected usage and deadlines. Include known constraints. Do not send secret keys or a production database through an ordinary contact form.

LISTIFY teamWebsites, apps and marketing from Prague since 2008

More articles

All articles →

Share this page

By email

Got an idea?

On a short call, we'll find out what you need and suggest the next step. Then you'll get a proposal with a fixed price and a timeline.

+420 771 166 199Mon to Fri, 8:30 a.m. to 4:00 p.m. (Prague time) · info@listify.cool

When should we call you?

Pick a day and a time window. We'll call you, and it takes about 15 minutes.

Day