This is in beta. If you find something wrong, let us know

Naming Conventions

Message Format

For request and response body field names and query parameter names case MUST be consistent, and SHOULD be either camelCase OR snake_case:

Examples:

// thisIsCamelCase

{
  "employeeId" : "AB1837"
}
// this_is_snake_case

{
  "employee_id" : "AB1837"
}

Fields that represent arrays SHOULD be named using plural nouns (e.g. products - contains one or more products). The object and field definition MUST be the same for the request and response body as well as corresponding query parameter values.

URI Component Names

URIs follow RFC 3986 specification. This specification simplifies REST API service development and consumption.

The guidelines in this section govern your URI structure and semantics following the RFC 3986 constraints.

URI Components

The structure of the URLs used within APIs SHOULD be meaningful to the consumers. URLs SHOULD follow a predictable, hierarchical structure to enhance understandability and therefore usability.

URLs MUST follow the standard naming convention as described below:

   https://gw.api.gov.au/namespace/project-name/v1/collection?fields=firstName,lastName
   \___/   \___________/\___________________________________/\______________________________/
     |           |                        |                                  |
  scheme     authority                   path                              query

URI Maximum Length

The total URI, including the Path and the Query, MUST NOT exceed 2000 characters in length including any formatting codes such as commas, underscores, question marks, hyphens, plus or slashes.

URI Naming Conventions

URLs MUST follow the standard naming convention as described below:

The following table provides a breakdown of how to construct the API URI.

URI Element Description Example
Protocol All APIs MUST be exposed using HTTPS. https://
Authority > Environment The domain of where the API endpoint will be exposed. Refer to the 'DNS' standard section for details. gw.api.gov.au
Path > API The API name which is derived from the business domain. e.g. /namespace/project-name
Any agency/department can specify the API name that they would like to expose their services on.
Path > Version The version of the API that is desired to be accessed by the consumer. e.g. /v1
All APIs must specify a version that follow the versioning scheme as specified in 'versioning' below.
Path > Collection The collection identifies a list of resources. The collection MUST be named using the plural representation of a noun. e.g. As part of the workforce API - a resource could be a list of employees.
Path > Resource The resource identifier which corresponds to an instance of the resource. e.g. As part of the project-name API - if there was a specific employee with id E13454. These details can be retrieved using GET /project-name/v1/employees/E13454
Query String > Parameters Query parameters MUST NOT be used to transport payload or actual data.
The following query parameters SHOULD be supported by your API where they would be useful:
  • fields - specify or restrict the fields to be returned
  • filter – conditions to restrict/filter the collection list
  • sort – specify the sort requirement
  • page – specify which pagination index to be return in a collection set
e.g. fields=first_name,last_name returns data element with only the first_name and last_name attributes

filter=creation_date gt 2001-09-20T13:00:00 and creation_date le 2001-09-21T13:00:00 and and post_code eq 3000 - return a collection of resources where the creation date is greater than 2001-09-20 1pm and less than or equal to 2001-09-21 1pm and post_code is 3000.

sort=date_of_birth desc - return a collection where the resources are sorted by date_of_birth in descending order.

page=10 – returns the 10th page index

Resource Names

API Designers MUST follow these principles when creating a REST API:

Note that this is the only place where hyphens are used as a word separator. In nearly all other situations camelCase OR an underscore character, ( _ ), MUST be used.

Good examples:

Bad examples:

Query Parameter Names

Field Names

The data model for the representation MUST conform to the JSON specification.

The values may themselves be objects, strings, numbers, booleans, or arrays of objects.

To help guide users through your API relational links MUST be provided. These links act as the navigation of your API advising users of where they can go to next.

A _links array SHOULD be provided for resources. This contains link objects that can refer to related resources in the system.

A link relation MUST contain the following elements:

Example:

"_links": [
    {
        "href": "/v1/customer/partner-referrals/ALT-JFWXHGUV7VI",
        "rel": "_self",
        "method": "GET"
    }
]

Request Headers

The following headers SHOULD be assumed by default on all requests.

Header Default Value
Accept application/json

Managing Dates

ISO8601 Formatted Dates

All implementations using dates MUST conform to ISO 8601 format.

In ISO 8601, date and time values are ordered from the largest to smallest unit of time: year, month (or week), day, hour, minute, second, and fraction of second.

The internationally recognised way to represent a date object is:

YYYY-MM-DD

The internationally recognised way to represent a time object is:

hh:mm:ss.fff

The component parts of these are described below:

Date Component Description Example
YYYY Four Digit Year 2019
MM Two Digit Month (with leading zero) 04
DD Two Digit Day (with leading zero) 27
T Set character indicating the start of the time element in a combined datetime format T
hh Two digits of an hour (00 through 23) 18
mm Two digits of a minute 38
ss Two digits of a second 12
fff Three digits of a millisecond (000 through 999) 123

When combined into a datetime, the object can be represented as follows:

2019-10-02T18:36:12.123

Usage of Timezones

When using ISO 8601 format the timezone is RECOMMENDED to be provided. This is due to the complexities that arise when consuming data and converting to local time.

The timezone can be represented in a variety of mechanisms, but is most commonly represented as an offset from GMT+0 (or Zulu time).

2019-10-02T18:36:12.123Z (with Z denoting Zulu time).

The convention here is as follows:

Date Component Description Example
Z Denotes Zulu Time (optional) Z
+ | - + represents positive offset from Zulu (e.g. ahead of Zulu). - represents negative offset from Zulu (e.g. behid Zulu) `+
hh Two digits of an hour (00 through 13) 10
mm Two digits of a minute (typically either 00, 15, 30 or 45) 30

To represent Australian Eastern Standard time (+10), the following format would be used:

2019-10-02T18:36:12.123+10:00

Date Field Naming Conventions

When using date fields, the following naming conventions for these fields should be used:

Examples

Good URL examples

List of employees:
GET https://gw.api.gov.au/e09284/v1/employees
Filtering is a query:
GET https://gw.api.gov.au/e09284/v1/employees?year=2011&sort=desc
GET https://gw.api.gov.au/e09284/v1/employees?section=economy&year=2011
A single employee in JSON format:
GET https://gw.api.gov.au/e09284/v1/employees/1234
All locations this employee works in:
GET https://gw.api.gov.au/e09284/v1/employees/1234/locations
Specify optional fields in a comma separated list:
GET https://gw.api.gov.au/e09284/v1/employees/1234?fields=job_title,start_date
Add a new location to a particular employee:
POST https://gw.api.gov.au/e09284/v1/employees/1234/locations

Bad URL examples

Non-plural endpoint:

GET https://gw.api.vic.gov.au/e09284/v1/employee
GET https://gw.api.vic.gov.au/e09284/v1/employee/1234
GET https://gw.api.vic.gov.au/e09284/v1/employee/1234/location

GET https://gw.api.gov.au/e09284/v1/employee
GET https://gw.api.gov.au/e09284/v1/employee/1234
GET https://gw.api.gov.au/e09284/v1/employee/1234/location

Verb in the URL:
POST https://gw.api.gov.au/e09284/v1/employee/1234/create

Filtering outside in the URL instead of the query string
GET https://gw.api.gov.au/e09284/v1/employee/1234/desc