--- type: Leaf title: Api Development Best Practices description: REST API design, security, versioning and documentation best practices for integrating Xero, Shopify and custom systems. resource: https://nationaldigital.com.au/platform-engineering/application-performance-optimisation/api-development-best-practices/ tags: - platform-engineering - Platform Engineering - API Development - System Integration - Application Modernisation - API development best practices - REST API design - system integration Australia - API documentation OpenAPI - legacy system modernisation - cloud engineering - API versioning strategy timestamp: '2026-09-15T08:24:37.461Z' language: en-AU publisher: National Digital author: Cameron Young authorRole: CEO readingTimeMinutes: 8 wordCount: 1467 datePublished: '2026-09-15' dateModified: '2026-09-15' pillar: platform_engineering canonical: https://nationaldigital.com.au/platform-engineering/application-performance-optimisation/api-development-best-practices/ --- _Home — Platform Engineering — Application performance optimisation — Api Development Best Practices_ # Api Development Best Practices REST API design, security, versioning and documentation best practices for integrating Xero, Shopify and custom systems. **Quick answer:** API development best practices cover REST design, early versioning, authentication and OpenAPI documentation; platform engineering is the broader practice APIs sit within. ## About this page - Written by Cameron Young, CEO - 8 min read - Updated 15 September 2026 _Platform Engineering — API Development — System Integration — Application Modernisation_ ## What are the best practices for API development? Design REST endpoints around business resources, version from day one, secure and rate-limit every call, and document with OpenAPI so integrations stay stable as systems change. **Additional Context** These practices matter most once an API has more than one consumer, whether that's an internal system, a partner, or a customer-facing app, because that's when undocumented, unversioned endpoints start breaking things unpredictably. _High confidence · Verified 15 Sept 2026_ *API Fundamentals* ## What Good API Development Looks Like API development is the work of designing, building, securing and maintaining the interfaces that let separate applications, services and data stores exchange information reliably. For a business running Xero for finance, a customer platform for orders and a warehouse system for stock, the API layer is what lets a sale in one system trigger an update in the others without someone re-keying data. Done well, an API is a stable, documented contract that other teams and systems can build against with confidence, even as the code behind it changes. ### REST API Design Best Practices Most business integration work still runs on REST, and the fundamentals haven't changed much: model endpoints around business resources rather than internal database tables, use HTTP status codes consistently, and keep responses predictable so consuming systems don't need special-case logic. Rate limiting and authentication belong on every endpoint from the outset, not retrofitted once something breaks. Versioning matters too: a breaking change to an endpoint that three internal systems and a partner integration depend on is a production incident waiting to happen, which is why [API-led integration](/platform-engineering/application-performance-optimisation/application-modernisation) approaches favour additive changes and clearly deprecated old versions over silent replacement. ### API Documentation and Versioning OpenAPI specifications (formerly Swagger) matter because they turn an API from something only its original developer understands into something a new team member, an external partner or an automated testing tool can work with directly. For businesses carrying older, poorly documented integrations, this is often where [staged legacy modernisation](/platform-engineering/application-performance-optimisation/legacy-application-modernisation) starts: documenting what exists, then improving it in place rather than replacing it outright. *API Development* ## Fixing API Development Before It Becomes a Liability **Problem:** Many growing businesses build APIs ad hoc, one integration at a time, with no shared standards for authentication, versioning or documentation. Each new connection to Xero, Shopify or a custom order system adds another undocumented dependency, so a single schema change can break three downstream systems at once and nobody can say which ones without checking manually. **Business Impact** - Time Wasted: Recurring hours spent manually reconciling data after integrations quietly break - Cost Implication: Costs compound as each new ad hoc integration needs its own rework later - Opportunity Cost: Engineering time spent firefighting instead of building new capability **Solution:** A staged approach: audit existing APIs and integrations, establish shared standards for authentication, versioning and documentation, then modernise the highest-risk connections first while keeping existing systems running. **Our Approach** 1. **Audit and map** _(Weeks 1-2)_: Catalogue every existing API and integration point across finance, sales and operations systems, noting which are documented and which aren't. 2. **Standardise** _(Weeks 2-4)_: Agree authentication, versioning and error-handling conventions that new and existing APIs will follow. 3. **Modernise in sequence** _(Ongoing, staged)_: Rebuild or document the highest-risk integrations first, in production, without a big-bang cutover. **Expected Outcome:** Integrations that survive a system upgrade without breaking, and a documented API layer new developers can work with in days rather than weeks. *Key Takeaways* ## What to Get Right in API Development Strong API development rests on consistent design, early versioning, real documentation and ongoing maintenance rather than one-off integration projects that are never revisited. - **Design APIs around business resources, not database tables** Endpoints that mirror how the business actually operates stay stable even when the underlying database schema changes, reducing breakage. _Important_ - **Version every API from the first release** Introducing versioning after three systems already depend on an endpoint turns routine changes into coordinated, risky migrations. _Critical_ - **Document with OpenAPI so the contract is explicit** A written specification lets new developers, partners and automated tests work against the API without needing to read the source code. _Important_ - **Treat integration as ongoing, not a one-off project** APIs need monitoring, authentication reviews and version retirement over time, the same as any other production system. _Important_ ## Why API Security and Design Discipline Matter APIs are a growing attack surface and a growing share of business infrastructure runs on cloud platforms they connect to, which raises the stakes on getting authentication and design right. - **Malicious attacks share of breaches: 59%** _Significance: high_ — Malicious or criminal attacks caused well over half of notified Australian data breaches in the first half of 2025, the largest single source in the OAIC figures. _(Source: OAIC Notifiable Data Breaches Report January-June 2025)_ - **Average cost per medium business cybercrime report: $97,200** _Significance: high_ — Medium businesses reporting cybercrime to ASD saw the average self-reported cost per report rise 55% year-on-year in FY2024-25. _(Source: ASD Annual Cyber Threat Report 2024-25)_ - **Business use of ICTs: 85%** _Significance: medium_ — Australian businesses reported using information and communication technologies in the year to 30 June 2022, up from 69% of businesses two years earlier. _(Source: ABS Characteristics of Australian Business 2021-22)_ **Methodology:** Figures drawn from the OAIC's biannual Notifiable Data Breaches report, the Australian Signals Directorate's Annual Cyber Threat Report, and ABS business characteristics survey data. *Context and Fit* ## API Development vs Platform Engineering: Where the Work Sits Platform engineering, in its recognised sense, is about building the internal developer platform and self-service infrastructure that lets a team ship and run software without hand-cranking servers and pipelines each time. API development is one of the disciplines that sits inside that wider practice, but it isn't the whole of it. Where platform engineering asks how systems run, scale and stay observable, API development asks how systems talk to each other reliably. The two overlap constantly: an internal platform needs well-designed APIs to expose its services, and API performance problems are often actually infrastructure or database problems wearing an API's name. That's a symptom worth investigating with [database query optimisation](/platform-engineering/application-performance-optimisation/database-optimisation) and [application performance tuning](/platform-engineering/application-performance-optimisation/code-optimisation) before assuming the API contract itself needs a rewrite. ## Where National Digital Fits National Digital works on the integration and API layer that connects the platforms a business already runs, Xero, MYOB, Shopify, HubSpot and the systems built around them, rather than replacing them wholesale. That typically means auditing what exists, designing or hardening the APIs that move data between systems, and sequencing changes so the business keeps trading throughout. For a broader view of how this fits into performance and reliability work generally, see [application performance optimisation](/platform-engineering/application-performance-optimisation). ## Talk to National Digital About Your API and Integration Layer Whether you're documenting existing integrations or building new ones, an experienced team can audit what you have and recommend a staged path forward without a rebuild you don't need. - [Book a Consultation](https://calendly.com/cameron-at-national-digital/discovery) - [Explore integration services](/platform-engineering/application-performance-optimisation/) - Email: enquiries@nationaldigital.com.au - Phone: 1300 800 855 ## API Development Questions Answered ### What is API development? API development is the work of designing, building, securing and maintaining the interfaces that let separate applications and systems exchange data. In practice, that means defining endpoints, choosing an authentication method, documenting the contract with a specification like OpenAPI, and versioning it so consuming systems don't break when the API changes underneath them. ### What's the difference between API development and platform engineering? Platform engineering builds the internal developer platform and self-service infrastructure a team uses to ship and run software. API development is one discipline within that broader practice, focused specifically on how systems expose and consume data reliably. A business can need strong APIs without needing a full internal platform, and vice versa. ### What are the most important REST API design best practices? Model endpoints around business resources rather than database tables, use HTTP status codes consistently, version from the first release, authenticate and rate-limit every endpoint, and document the API with an OpenAPI specification so other systems can integrate against a stable, predictable contract that survives future changes without warning. ### What is Swagger used for in API development? Swagger, now known as the OpenAPI Specification, is a standard format for describing an API's endpoints, request and response formats and authentication requirements. Teams use it to generate interactive documentation, auto-generate client code, and let automated tools validate that an API behaves as specified before it reaches production. ### Should we hire an API development company or build the capability in-house? It depends on how central integration is to how the business trades. Occasional, low-risk API work can often sit with an existing developer or a generalist agency. Where APIs connect core systems like finance, orders and stock, engaging specialists experienced in staged, reversible integration work typically reduces the risk of a change breaking something nobody expected. ### How do you modernise poorly documented legacy APIs without a full rebuild? Start by auditing what exists and documenting current behaviour, even if the code itself isn't touched yet. From there, standardise authentication and versioning on new work, then progressively bring the highest-risk existing integrations up to the same standard, keeping the business running throughout rather than replacing everything at once. ## Related reading - [Database optimisation for Australian latency](/platform-engineering/application-performance-optimisation/database-optimisation/) - [Code optimisation for legacy applications](/platform-engineering/application-performance-optimisation/code-optimisation/) - [Asset optimisation for faster pages](/platform-engineering/application-performance-optimisation/asset-optimisation/) - [Performance testing for Australian users](/platform-engineering/application-performance-optimisation/performance-testing/) - [Application Modernisation](/platform-engineering/application-performance-optimisation/application-modernisation/) - [Legacy Application Modernisation](/platform-engineering/application-performance-optimisation/legacy-application-modernisation/) ## Related **Parent:** - [Application performance optimisation](/okf/platform-engineering/application-performance-optimisation.md) **Related:** - [Database optimisation for Australian latency](/okf/platform-engineering/application-performance-optimisation/database-optimisation.md) - [Code optimisation for legacy applications](/okf/platform-engineering/application-performance-optimisation/code-optimisation.md) - [Asset optimisation for faster pages](/okf/platform-engineering/application-performance-optimisation/asset-optimisation.md) - [Performance testing for Australian users](/okf/platform-engineering/application-performance-optimisation/performance-testing.md) - [Application Modernisation](/okf/platform-engineering/application-performance-optimisation/application-modernisation.md) - [Legacy Application Modernisation](/okf/platform-engineering/application-performance-optimisation/legacy-application-modernisation.md) - [Aws Cloud Data Engineering](/okf/platform-engineering/application-performance-optimisation/aws-cloud-data-engineering.md) # Citations - [OAIC Notifiable Data Breaches Report January-June 2025](https://www.oaic.gov.au/news/blog/latest-notifiable-data-breach-statistics-for-january-to-june-2025) — Malicious or criminal attacks caused the majority of notified Australian data breaches in early 2025. - [ASD Annual Cyber Threat Report 2024-25](https://www.cyber.gov.au/sites/default/files/2025-10/Annual%20Cyber%20Threat%20Report%202024-25.pdf) — Average self-reported cybercrime costs rose sharply for medium and large Australian businesses in FY2024-25.