API Changes and Versioning
As HMPPS Integration API evolves, more features will be added, and features that already exist will change. Both consumers and MOJ must be prepared to handle these changes, and to manage them carefully.
There will broadly speaking be two kinds of changes - “non-breaking” changes, where consumers should be able to use the new version without modifying their usage, and “breaking” changes where we would expect that consumers would not be able to seamlessly use the new version.
Non-Breaking Change
We would like to minimise the number of breaking changes, and where this is not possible, we will increment the API version and manage the migration.
- MOJ - must not change or remove an existing data element unless we are certain it is not in use
- MOJ - must update documentation to reflect any changes
- MOJ - may add new elements and change/remove elements that we know are not in use
- Consumers - implementation must accept new elements and changes to elements that are not in use (i.e. it must be resilient to non-breaking API changes)
Breaking Change
Where a non-breaking change is not possible, there is then a breaking change. In this case, we will increment the version of the API
- MOJ - must update documentation, and explicitly call out the change between versions
- MOJ - must distribute the new documentation as soon as practical
- MOJ - must run both versions of the API, as long as this is practical, for at least 1 month
- Consumers - must commit to moving to the new version of the API within a reasonable timescale, usually 1 month
- Depending on the size of the change, MOJ may require the Consumer to go through additional re-assurance steps
Ongoing Assurance
As part of including new functionality into the system, new processes will be available to be undertaken via the API. As these are introduced, we will ask consumers to go through further rounds of assurance, broadly similar to the initial round described above.
URI Path
Where versioning must be implemented, it will be in the form of a path parameter:
https://integration-api.hmpps.service.justice.gov.uk/v1/images/123456
Versions will increment by major version only and no minor version updates will be supported.