- What is this design standard?
- How to apply the design standard
- The choice behind REST
- Sample OpenAPI Definition
- API
- Resource
- Resource Identifier
- Representation
- Namespace
- Operation
- API Documentation
- API Development
- API Developer Experience & Ease of Use
- API Stability
- API Design Maturity
- Message Format
- URI Component Names
- Field Names
- Link Relation Names
- Request Headers
- Managing Dates
- Examples
- Versioning Scheme
- Major Version
- Minor Version
- Minor and Patch Documentation
- Backwards Compatibility
- End of Life Policy
- API Deprecation
- Request Headers
- HTTP Request Methods
- Request Payload Formats
- Idempotency
- Pagination
- Filtering and Sorting
- Response Headers
- HTTP Response Codes
- Response Payload
- Error Response Payload
- Input Validation
- Error Samples
- API Design
- Transport Security
- Authentication and Authorization
- Abstraction
- Rate Limiting
- Error Handling
- Audit Logs
- Input Validation
- Content Type Validation
- Gateway Security Features
- Protective Marking
- Hypermedia - Linked Data
- HATEOAS
- Hypermedia Compliant API
- Link Description Object
- Link Relation Type
- Query Parameters
- Pagination Response
- Out of Range
- Caching
- Current Guidance
- Testing Tools
- API STANDARDS REFERENCED
Australian Government - API Design Standard
Design Standards for Whole of Australian Government (WoG) Application Programming Interfaces (API)s.
Introduction
As government services modernise and increasingly rely more on digital platforms and approaches, new challenges are surfacing in the connectivity, service interoperability and data security aspects of solutions.
These challenges are further magnified when agencies are designing services that are intended to be consumed by other government entities across the Whole of Australian Government (WoG); introducing challenges with data consistency, identity management and alignment to government policy.
Agencies looking to effectively address these challenges require a strategic approach that considers both the current known consumers and their requirements, as well as the unknown consmers in the future will need.
Typically to address this, government departments are expected to create a holistic integration strategy as a critical component of their technology arsenal which streamlines re-use of services, simplifies existing environments and de-risks implementations. A key part of this integration strategy is the standardised design of interfaces between the different systems.
A standardised interface design promotes interoperability between systems, but also allows developers building connections between the systems to be more productive not having to learn a new standard with each new system.
Online resources currently exist that teams, agencies and departments can utilise when looking to building and launch APIs and integrations. There is however a gap in official, ratified standards in the API and integration space and even more so within the Product Management community around APIs in government.
To address this need, in 2019 the Australian Data and Digital Council (ADDC) approved the creation of National API Design Standards following Victoria and other jurisdictions individually progressing API Design Standards for their own jurisdictions’ API developers. The opportunity for a national approach was recognised as mutually beneficial to all participating States, Territories and the Commonwealth.
The broad goals of this National API Design Standard are to:
- Create a technical API design standard to be used across the WoG for cross-jurisdictional data sharing
- Improve overall quality of the APIs being shared, as well as the literacy around APIs and integrations
- Build a cross-jurisdictional working group of API experts who can continue to foster and champion the standard across the Whole of Australian Government.
The mission is to ensure the highest standards are obtained by defining a base level of delivery required to meet the design standard, and only describing expansion when further comment is required.
Document Audience
The audience for this document is API Developers, Solution Architects and Business Analysts that are looking to design a new API or make changes to an existing service in order to improve aspects of usability, readability or security.
This document has been written with a view of being used internally within the Australian Government however it is being released for broader adoption by individuals or organisations that are wanting to build APIs that are interoperable with the WoG standard.
Document Semantics, Formatting, and Naming
The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.
The words REST and RESTful MUST be written as presented here, representing the acronym as all upper-case letters. This is also true of JSON, XML and other acronyms.
Machine-readable text, such as URLs, HTTP verbs, and source code, are represented using a fixed-width font.
Contact Information
- State of Victoria - apiteam@dpc.vic.gov.au
- State of New South Wales - support@onegov.nsw.gov.au
- State of Queensland - tuo@qld.gov.au
- State of Tasmania - digital@dpac.tas.gov.au
- State of Western Australia - WAPlatforms@dpc.wa.gov.au
- State of South Australia - svc-oft-appservices@sa.gov.au
- Australian Capital Territory - api@act.gov.au
- Northern Territory - ictinfrastructure.ntg@nt.gov.au
- Commonwealth of Australia - platforms@dta.gov.au