Healthcode APIs are versioned to enable enhancing, including adding new resources to, the existing API bundles without breaking existing integrations. The caller must specify the appropriate version using HC-API-Version header parameter while calling the APIs. Where a value is not specified, version 1 is assumed. However it’s recommended you always supply the HC-API-Version header parameter even if using version 1.

Note, Healthcode may occasionally change implementation logic as well as interface (input/output parameters, format) on existing APIs where the change is deemed to be backward compatible. Calling systems must ensure integration implementation is flexible to accommodate such changes.

What changes do Healthcode consider as backward compatible?

• Partially or fully changing an API endpoint address where it’s published through a discovery document. For such a change we will ensure the corresponding discovery document at the well-known location is updated to reflect the new and correct endpoint URI.
• Adding new API endpoints to the library.
• Adding new optional input parameters to existing APIs.
• Changing a mandatory input parameter to optional.
• Adding new values to the list of allowed values for enumerated input parameters.
• Adding new attributes to existing API responses.
• Changing the order of attributes in existing API responses.

Deprecation and sunsetting of APIs

Healthcode continually evolve the API implementations to improve durability, availability, performance, and security; to enhance the APIs’ functionality; to align with changing industry standards; and to ensure we continually improve our service in general.

Naturally, as we introduce new version of APIs, we need to gradually phase out older versions, in order to maintain the highest quality of service standards that we aim for.

When phasing out the APIs, Healthcode strives to maintain consistency and predictability of our API interfaces. There are two primary aspects of the phasing out process – deprecation and sunset.

• We will maintain active support for the 2 most recent versions of APIs. For example, when delivering version 3 of an API, we will mark version 1 as deprecated.
  
  When deprecating APIs, or API versions, those APIs are marked as deprecated inline within the documentation on this portal.
  
  Deprecated APIs will continue to be available, but integrating systems are discouraged from using those versions. Integrators SHOULD plan to upgrade to the latest available version of the APIs.

• Deprecated APIs are decommissioned (or sunset) periodically.
  
  When sunsetting the APIs, we first update the documentation inline within this portal to mark the affected APIs, or API versions, as scheduled for sunset, and also, will notify subscribing customers through other channels where applicable.
  
  APIs scheduled to be sunset will continue working for a certain duration of time, as communicated within the inline message on this documentation portal or within the notification email. At the end of the notification period, the API will be decommissioned and will no longer be available. Integrators MUST upgrade to the latest available version of the APIs before the sunset date.
  
  Sunset may apply to a single deprecated version of an API, or may also happen in a batch, with multiple versions of API decommissioned in one go.
  
  Note, deprecation and sunset aren’t applied strictly in sequence. APIs, or API versions, may be directly scheduled for sunset, without having been marked for deprecation before.