Accessing the API

ADC publishes a Swagger UI page for developers to experiment with our services.

Note: The test environment is currently ONLINE.

Key resources

Test

Demo matching site using the test environment: https://demodms.services.bdm.qld.gov.au/

Endpoint: https://testdms.services.bdm.qld.gov.au/ws/api

Swagger: https://testdms.services.bdm.qld.gov.au/ws/api/api-docs?url=/ws/api/swagger.json

UserID: testclient1

Web service password: testclient1password

Please note test access is limited to traffic originating from Australia. Should you require access from outside of Australia, please contact us with a list of IP addresses for whitelisting.

Production

Endpoint: https://dms.services.bdm.qld.gov.au/ws/api

Swagger: https://dms.services.bdm.qld.gov.au/ws/api/api-docs?url=/ws/api/swagger.json

Please note production access is only granted following full approval of your connection which includes any payments required, the finalisation of your agreement, and the completion of successful testing.

Authentication

Headers

All headers described below are mandatory.

Header	Definition

Header	Definition
X-Authorization	Primary authorization header containing the signature for the full request. See Generating the Authorization header for more information.
X-Date	Date and time stamp of the request. The request’s X-Date is compared against the ADC service’s within a threshold of five (5) seconds in order to support slower requests and an acceptable drift of 20 seconds. Use the ISO 8601 format: yyyy-MM-ddTHH:mm:ssZ. yyyy - current year MM - current month starting at 01 for January dd - day of month starting at 01 HH - 24 hour format time of day mm - minutes in the current hour starting at 00 ss - seconds in the current minute starting at 00 Z - Your timezone offset. e.g. +1000 for Australia/Brisbane.
X-UserID	Your web service username provided by the ADC access team.
X-RemoteUserID	The end user’s identifier and is useful for identifying who in your organisation started the request. This value is stored for tractability in the event of misuse of ADC services. Your service must store the X-RemoteUserID for auditing purposes and you will be utilised to trace misuse of services.

Generating the Authorization header

The Authorization header is a HmacSHA256 hash made up of the user ID (X-UserID), remote user ID (X-RemoteUserID), date/time stamp (X-Date) and the full request, each separated by a colon. These are combined in the format:

X-UserID:X-RemoteUserID:X-Date:Request

This combined value is then hashed with your web service’s password and encoded in base 64.

For example, a request of at 2nd January 2019 at 05:04:03 Australia/Brisbane time would result in:

Header	Value

Header	Value
X-Date	2019-01-02T03:04:05+1000
X-UserID	some user id (testclient1 in the test environment)
X-RemoteUserID	some remote user. This is used to track your own end users.
Web service password (do not include this header)	some secret (testclient1password in the test environment)
Request (this is not a header, this is the request body)	The request body in JSON
X-Authorization	“some user id:some remote user:2019-01-02T03:04:05+1000:some request” with a HmacSHA256 using “some secret” and converted to base 64.

Example request

Do not use this testing tool service for your production access. This is only intended for testing our services using the test client details provided above.

Liavaag.org has a useful tool for creating HMAC authorization keys: https://www.liavaag.org/English/SHA-Generator/HMAC/

The easiest way is to set the time a little ahead in the Input and in the X-Date in Swagger test pages. Then try the service when it enters the time range (or just try multiple times until the outside boundaries error goes away).

Fill in the generator site simliar to below:

Use the resulting Base64 hash as your Authorization header in the Swagger test page at:
https://testdms.services.bdm.qld.gov.au/ws/api/api-docs?url=/ws/api/swagger.json
Note: Make sure the request body matches exactly what you have in the Input field for generating the hashed result. This includes removing any spaces or new line characters that may be different.

You should see a response similar to below:

Testing your access

A health check service has been added that clients can test their authentication against:

https://testdms.services.bdm.qld.gov.au/ws/api/health/check

Using the testclient1 / testclient1password API, create your request the same as described above, but without a request body. i.e. The authorization header should be a hash of (without quotes): “testclient1:testremote:2021-01-22T13:23:03+1000:”

You should receive a response with “okay” if the authentication is successful. Otherwise, you will receive the standard responses outlined above (i.e. 401).