API development designed contract first so integrators stop guessing

Adding an optional field, adding an endpoint or adding an enum value that clients are told to tolerate are safe. Removing a field, renaming anything, tightening validation, changing a default or altering the meaning of an existing value are not. Breaking changes go into a new version, and the previous version stays available for a stated support window written into your terms rather than decided under pressure. We instrument the gateway so you know which clients are still calling the old version and can contact them by name instead of announcing a shutdown and hoping. Deprecation headers, a changelog and email notice before the sunset date cost very little and prevent the incident that damages a commercial relationship.

• Versioning in the URL path or a header, chosen once and applied consistently
• A written support window per version, published with the documentation
• Per client usage visibility so you know exactly who is affected
• Deprecation headers and a changelog integrators can subscribe to
• Contract tests that fail the build when a change breaks the published schema

Rate limiting protects both sides. It stops one enthusiastic integrator from degrading service for everyone, and it gives you a commercial lever if you sell tiered access. Limits are applied per client with clear headers telling the caller their remaining quota and when it resets, because a limit that returns a bare error teaches integrators nothing except to retry harder. We add idempotency keys on anything that creates or charges, so a network timeout followed by a retry does not produce two orders. Payload size caps, request timeouts, structured audit logging and alerting on unusual patterns round it out. Where the API carries personal information, the Privacy Act 1988 obligations apply to it exactly as they do to your website.

So documentation is treated as part of the deliverable rather than an afterthought. Generated reference from the contract, a getting started guide with a real worked example, copy and paste requests, plain language explanations of the error codes and what to do about each one, and a sandbox environment with seeded test data that behaves like production including its failure modes. Where volumes justify it we generate typed client libraries in the languages your integrators actually use, which removes a whole category of avoidable support questions. If the API supports your own applications as well, this same documentation is what stops your mobile team and your web application team implementing the same rules two different ways.

If the goal is connecting two systems you already run, an integration platform is often faster and cheaper than building and hosting an interface. Tools covered in n8n automation or Zapier automation handle a great many system-to-system flows without a custom build, and the honest recommendation for a modest volume connection is usually one of those. If the aim is a single nightly data export to a reporting tool, a scheduled file drop is more robust than a live interface and nobody has to be on call for it. Build an API when there will be multiple consumers, when the data must be current rather than daily, or when the interface itself is part of what you sell. Suppliers and distributors moving toward the last of these usually pair it with a supplier portal so partners without developers are not excluded.