Skip to main content
Version: 1.2

Compatibility rules

Compatibility rules for NZ published FHIR APIs​

info

All serious designers/developers of APIs need to recognise the substantial time and effort other parties may invest to develop an application that consumes their API -- this consideration applies equally to RESTful FHIR APIs.

It is reasonable that parties who develop applications consuming a FHIR API shall expect to be able to depend on the continuing functioning of that API without breakage, erosion of functionality or loss of data quality (to the extent that the API controls data quality).

Requirements​

Designers / developers proposing breaking change1 to an existing, published FHIR API MUST adhere to the following compatibility rules for Health NZ public APIs:

  • MUST ensure that all applications using the existing published API version can continue to depend on it without change for a period of at least three years from introduction of the new API version💡

  • MUST ensure all affected API-consuming parties are given opportunity to provide feedback on the proposed changes💡

  • MUST ensure all applications already consuming the existing API receive warnings for a minimum period of one year before that API version is withdrawn from support and no longer usable.💡

Footnotes​

  1. For a crisp and useful definition see this breakdown of breaking change as published by GitHub. ↩