API Discoverability

The API is designed to be (to some extent) self documenting. It provides a number of endpoints that can:

  • List all supported resources.
  • Output metadata and documentation about the fields & capabilities of a resource as HTML or XML.
  • Output XSD schemas representing a resource.

Listing available resources

To view a list of resources available for the API in your browser, access the HTML version:

https://www.clientwebsite.nz/API/V3.html

You will need to provide the API key as the basic auth username when prompted.

Alternatively you can send a request to the API via Postman or some other API client to this endpoint:

https://www.clientwebsite.nz/API/V3

This will show a list of all accessable resources (there are a lot!).

Individual resource documentation

The HTML resource list will provide a link for each resource. If you click a resource in this list, or directly access the url https://www.clientwebsite.nz/API/V3/[resource].html you will be provided with:

  • A list of fields in the resource. This list is the definitive list of fields for that resource on that site - including any columns & data structres that may have been implemented for this particular website.
  • A list of any related resources that can be joined to in a resource specification.
  • A link to the XSD for that resource.
  • Other useful links, including the ability to import or export data to/from spreadsheets for the given resource.

XSD Schemas

We provide auto-generated XSD schemas for each resource. However it is highly recommended to ensure your code is not too tightly coupled to it.

Read the XSD documentation for further information about these schema, tips on using them and the ability to disable them if required.