Definitions Catalogue

Using the API

HATEOS

Most of the resources returned the API follow the HATEOS approach: links are provided to help you navigate around.

This API uses HATEOS for things like:

paging
getting specific details about defintions

HATEOS in this API follows this general pattern:

{
    "content": { ... the resource data ...},
    "links": [
        {
            "rel": "a_name_for_the_link",
           "href": "a_link_to_related_things"
         },
         ... more rels/hrefs ...
    ]
}

Paging

This API pages results.

The page query parameter selects which result page to return.

The size query parameter specifies how many results per page to return. The default is 20 and the maximum is 100.

A page of results give you helpful information about navigating the other result pages.

Result pages look like this:

{
  "content": [
	... the result page data ...
  ],
  "numberOfElements": 123,
  "firstPage": true,
  "lastPage": false,
  "totalPages": 7,
  "links": [
    {
      "rel": "first",
      "href": "http:/api.gov.au/definitions/api/search?query=car&page=1&size=20"
    },
    {
      "rel": "last",
      "href": "http:/api.gov.au/definitions/api/search?query=car&page=7&size=20"
    },
    {
      "rel": "self",
      "href": "http://api.gov.au/definitions/api/search?query=car&page=1&size=20"
    },
    {
      "rel": "next",
      "href": "http://api.gov.au/definitions/api/search?query=car&page=2&size=20"
    }
  ],
  "id": {
    "rel": "self",
    "href": "http://api.gov.au/definitions/api/search?query=car&page=1&size=20"
  }
}

The web version

There is a web version of the catalogue that mirrors the functionality of this API.

In general, the API uri's follow the same pattern as the web ones but with the '/api/' path segment removed.

For example:

http://api.gov.au/definitions/definition/other/de55 <-- the web version
http://api.gov.au/definitions/api/definition/other/de55 <-- the api version

So to get an easy head start on what you can do wit the API, head over to the web version and take a look.

Rate Limiting

At the moment there is no imposed rate limiting.

We'll monitor the service and impose limiting if it has trouble keeping up.

Back

Collaborate