Change and Release

How ACC plans to update API's

This document contains information regarding:

  1. The change and release policy for API’s
  2. The change and release process
  3. Terms and Definitions

Policy

ACC will support at maximum two versions of the same API at any given time. That is:

  • N: Current version
  • N-1: Previous version

When a new version is introduced, the current version becomes N-1 and the old version will be retired

ACC will endeavour to limit API version updates. Updates will try to maintain a minimum of a six month interval period.  ACC reserve the right to change the interval period to accommodate business or security needs.

Once an API release is grandfathered, it will continue to be supported for six months before retirement.

New version of API will be introduced only if it is a breaking change.

The sector will be advised regarding a plan to introduce a new, or change a version of, API via the developer portal.

The API will be made available via the sandpit to facilitate sector testing and trials.

Terms and Abbreviations

Terms

Description

Breaking Change

Examples

Changes to a response or error message

Removal of HTTP Verb

Non-Breaking Change

There will be multiple updates overtime with backward compatibility to a major version

Examples

Addition of new resources

New JSON properties

New HTTP Verb

Major Release

Label = x.0. Example: 3.0.

Description: Software vendors need to update their software.

Examples:

  • The interface changes:

o An endpoint is changed.

o A field is removed.

o The structure of the response changes.

  • The structure of a code table changes.
  • The text of an error message changes, if the vendor’s code relies on specific text.

Minor Release

Label = x.1, x.2, x.3 etc.

Description: Software vendors don’t need to change their software.

Examples:

  • A new endpoint is added.
  • Code-table data changes.
  • An API has back-end changes that don't affect the interface.
  • Specifications or other documents are updated, with no change to code.

Invoice

Although the terms ‘invoice’ and ‘schedule’ are used interchangeably, in fact each schedule line item is an invoice, with a contract identifier, service details, and amount.

Organisation

The employer of a health provider, or the umbrella group including that employer.

Example: Southern Cross

An organisation has an HPI-ORG identifier, like GA1234.

Provider

A health professional such as a doctor or physiotherapist, with an HPI-CPN identifier like 12ABCD; or a person providing services, such as a taxi driver or home help worker.

Schedule

Often referred to as an invoice, a schedule contains one or more line items, each one being an invoice for a given amount.

Service code

Identifies the health service that has been provided, for which the cost is charged to ACC. A service code is always linked to a contract, a purchase order, or a regulation identifier, and identified with a flat fee, or a unit, time, or distance measure.

Sometimes called an ‘unload reference’.

Vendor

A business providing health treatment. Example: Capital Coast Health

A vendor has a GST number and a bank account, and one or more contracts with ACC.

(In this case, vendor does not refer to a software vendor, the supplier of a software system used for instance by medical practices.)

Change and Release Process