Api Development Practices
Practical API standards for growing Australian teams: versioning, auth, testing, governance. See how to modernise yours.
Quick answer:Durable API development pairs versioned REST or GraphQL endpoints with OAuth 2.0 authentication, automated contract testing, and a documented plan for wrapping legacy systems.
- Platform Engineering
- API Development and Management
- System Integration
Quick answer
What does good API development practice actually look like?
Versioned REST (or GraphQL) endpoints, OAuth 2.0 authentication, automated contract testing, and a published deprecation policy agreed before the first integration ships.
Additional Context
These practices matter most once a business has more than a handful of integrations depending on the same backend systems, where an untested change can break several consumers at once.
Sources
- API Design Standard
Whole-of-government standard for designing consistent, well-documented APIs.
- Consumer Data Right technical standards
Binding API specifications for data holders in CDR-regulated sectors.
Platform Engineering
What good API development looks like
Most businesses already have APIs in production, even if nobody set out to build a platform. A Shopify webhook feeding Xero, a HubSpot integration pulling lead data into a sales dashboard, a custom endpoint connecting a warehouse system to a courier - each one was built to solve an immediate problem, on its own timeline, by whoever had capacity that sprint. The practice of custom API development only becomes a discipline once a business has enough of these endpoints that a change to one risks breaking three others.
The practices that separate a resilient integration layer from a fragile one are not exotic. They cover versioning so a schema change does not silently break an existing consumer, authentication that does not depend on a shared secret pasted into five config files, and documentation a new developer can actually read. Teams that get REST API versioning right from the first external integration rarely need to renegotiate it later.
Where the standard breaks down
The common failure mode is not a lack of technical skill. It is sequencing: authentication gets retrofitted after three systems already depend on a hardcoded key, or a breaking field change ships on a Friday because no contract test existed to catch it in review. Fixing this after the fact costs more than building it in from the second integration onward.
Platform Engineering
Integration Debt From Ad-Hoc API Development
Problem
Each integration gets built as a one-off: its own authentication, its own error handling, no shared contract. The moment one of those ad-hoc endpoints needs to change, nobody can say with confidence what else will break.
Common Pain Points:
- No shared authentication pattern Each integration invents its own login flow, so credential rotation becomes a manual, error-prone exercise.
- Breaking changes ship unannounced A field renamed in one release silently breaks three downstream systems nobody tested against it.
- Undocumented endpoints New developers reverse-engineer behaviour from logs because no specification exists to read.
- Inconsistent error handling Every integration interprets failure differently, making automated retries and monitoring unreliable.
Business Impact:
Time Wasted: Recurring engineering hours spent diagnosing breakages after undocumented changes
Cost Implication: Maintenance cost climbs with every new integration added on an ad-hoc basis
Opportunity Cost: Engineering capacity spent firefighting broken integrations that could otherwise go toward shipping new features.
Solution
Audit what's already live, agree a shared versioning and authentication standard, retrofit contract tests, then wrap legacy systems in a documented API layer without rewriting them.
Our Approach:
- Audit existing endpoints and consumers (1-2 weeks, typically)
Map every API currently in production, who calls it, and what breaks if it changes.
- Define the shared standard (2-3 weeks, typically)
Agree versioning, authentication and error-handling conventions all new and retrofitted endpoints must follow.
- Retrofit contract tests (4-6 weeks, typically)
Add automated schema validation to existing endpoints so breaking changes surface in CI before they reach production.
- Wrap legacy systems behind the standard (6-12 weeks, typically)
Build an API layer over ageing core systems so new integrations connect without touching underlying application code.
Expected Outcome: A documented API standard that new integrations follow by default, with breaking changes caught in testing before a partner discovers them in production.
Key Takeaways
API practices that prevent integration debt
- Version every endpoint before the first external consumer connectsCritical
Once a partner or internal system depends on an endpoint shape, changing it without a version path forces a synchronised release across every consumer.
- Authentication design decides how painful credential rotation becomes laterImportant
Systems built without OAuth 2.0 or token-based auth from day one tend to end up with hardcoded credentials scattered across consuming applications.
- Contract testing catches breaking changes before they reach productionImportant
Automated schema validation against a published contract flags a breaking field change in CI, well before a partner integration team finds it six weeks later.
- Legacy systems need an API layer, not a rewrite, to join the integration stackImportant
Wrapping an ageing core system in a well-documented API lets new tools connect without touching the underlying application logic.
Durable API development rests on versioning, authentication design, contract testing and a deliberate approach to wrapping legacy systems without rewriting them outright.
API Standards Shaping Australian Integration Work
Australian government and sector regulators increasingly publish binding API standards covering design, data sharing and privacy obligations for integration work.
Whole-of-government standard
API Design Standard
Significance: highThe Digital Transformation Agency publishes a mandatory API design standard covering REST conventions, versioning and documentation for government digital services.
Source: Digital Transformation Agency, API Design Standard
Mandatory for banking and energy
CDR Technical Standards
Significance: highConsumer Data Right technical standards set binding API specifications that data holders must implement for financial and energy data sharing in Australia.
Source: Data Standards Body, Consumer Data Right
Applies to personal data APIs
Privacy Act API Obligations
Significance: mediumAny API transmitting personal information must meet Australian Privacy Principles security and handling obligations set out in the Privacy Act 1988.
Source: OAIC, Australian Privacy Principles guidance
Methodology
Points reference published standards from the Digital Transformation Agency, the Consumer Data Right Data Standards Body, and the Office of the Australian Information Commissioner.
Scaling the standard
Practices that hold up as integration volume grows
Every endpoint carries a version in its path or header, with deprecation following a published timeline that consumers can plan against. Authentication runs through a standard pattern, commonly OAuth 2.0 authentication, so rotating a credential means updating one identity provider, not hunting through five codebases. Schema contracts get tested automatically, so a field rename or type change fails a build before it reaches a partner's production system.
Bringing legacy systems into the standard
The temptation with an ageing core system is to leave it untouched and route everything else around it. A better pattern is wrapping it in a dedicated API layer that exposes a clean, documented contract while the legacy logic underneath stays exactly as it is. This is how booking channel manager integrations typically get built: the property management core stays in place, and a purpose-built API layer handles the real-time availability sync with each channel. Teams that skip this step and modify the legacy core directly often find the next update cycle reintroduces the exact bug they'd already fixed.
Common questions about API development practices
What's the difference between API development and system integration?
API development builds the interface itself - the endpoints, authentication, versioning and documentation a system exposes. System integration is the broader work of connecting that API to other platforms, mapping data between them, and keeping the connection working as each side changes. A business doing serious integration work usually needs both: a well-built API to expose, and integration logic to consume it reliably.
Is REST still the right choice, or should new APIs use GraphQL?
REST remains the practical default for most integration work because it's well understood, cacheable, and simple to document with OpenAPI. GraphQL earns its complexity when a frontend needs flexible queries across many related objects, such as a dashboard pulling fields from several systems in one call. Most businesses are better served starting with REST and reaching for GraphQL only when a genuine query-shape problem appears.
What does API-first development actually mean day to day?
It means designing and agreeing the API contract, its endpoints, request and response shapes, and error handling, before writing the implementation. Teams typically draft this in OpenAPI or a similar specification, review it with consuming teams, then build against the agreed contract. This catches mismatches during design review, well before a failed integration test weeks later.
How long does retrofitting proper API practices onto an existing system take?
It depends heavily on how many consumers already depend on the existing endpoints and how undocumented they are. A single internal integration with one consumer might take a few weeks to version and test properly. A core system with a dozen undocumented endpoints feeding multiple partners is a staged project that gets scoped and sequenced across several phases.
Do we need a dedicated API development company, or can our team manage this?
An internal team with solid engineering discipline can absolutely build and maintain good APIs. External specialists earn their place when the business lacks spare capacity to do the audit and retrofit work properly, when the legacy system is unfamiliar territory for the internal team, or when several integrations need building in parallel against a tight deadline.
What's the actual risk of skipping API versioning?
Any change to an unversioned endpoint - a renamed field, an altered data type, a removed parameter - breaks every consumer simultaneously, with no warning and no fallback path. Versioning gives consumers a predictable migration window ahead of any change. It's one of the cheapest practices to adopt early and one of the most expensive to retrofit once a dozen systems depend on current behaviour.