This section defines versioning for components within the iHub and SOH. These components include:
- APIs
- Standard Data Model.
- SOH Field schemas and POLE tags
Information in this section is derived from sections 2.1, 2.3, and 3 in the iHub Versioning Strategy documentation and sections 3.1, 3.2, and 3.3 in the DPC API Technical Data and Documentation Standards documentation. These documents are designed to support any new technical and development resource onboarding to the iHub.
For full technical standards on API versioning, refer to the DPC API Technical Data and Documentation standards document.
The iHub development team, and any forces developing APIs through the iHub C4E, are expected to tag APIs with a status as follows:
- Alpha - early prototyping - the API specification is available and might be available for testing via a mocked sandbox service or an integration environment.
- Private Beta - the API is available in production but only to a limited number of connecting applications. It might be subject to breaking changes
- Public Beta - the API is available in production to all forces/API Consumers. It might still be subject to breaking changes.
- Live - there will be no breaking changes - if breaking changes become necessary, a new version of the API will be published subject to the semantic versioning rules (see below).
- Deprecated - the API is still available (to existing API Consumers only) and service levels still apply. There will be no updates, no new keys issued, and new integrations are not permitted. This will start the period to full retirement of the API.
- Retired - the API is no longer available for use.
When versioning the iHub components, semantic versioning) will be used where applicable. This is a recognised industry standard for versioning.
This will follow the form of MM.mm.pp, where the following is applicable:
- MM is a major semantic version which may create breaking changes to other systems such as addition of ‘required/mandatory’ elements in the schema.
- mm is a minor version upgrade with non-breaking changes such as the enhancement of the supporting schema with ‘optional’ elements in the schema.
- pp is patch or cosmetic change, for example:- changing the trim text within the description held in the supporting schema due to a typo.
Breaking changes occur when existing API usage is affected. The following are examples of breaking changes:
- Changing the format of request or response data (e.g. switching from JSON format to XML format)
- Changing the data type of a resource (like changing from a string to an integer)
- Changing the name of a resource
Non-breaking changes do not affect existing API usage. The following are examples of non-breaking changes:
- Adding new methods (e.g., PUT, POST) for a resource.
- Adding new resources and endpoints.
In line with this versioning strategy, the following API-centred change patterns are leveraged:
| Nature of change between versions | Driven by | Sequence |
|---|---|---|
| Non-breaking (e.g. 1.11.0 to 1.12.0) | API Provider | API Consumers are migrated to the latest minor version |
| Breaking (e.g. 1.12.00 to 2.0.0) | API Consumer | API Consumer will make a decision to move to the new major version |
The iHub will have a strategy of only supporting a limited number of versions of an API. Under some circumstances, due to major versions being released in close time scales, this may be increased, but only by exception.
For full details on when APIs will be deprecated, refer to section 3.4 of the DPC API Technical Data and Documentation Standards documentation.
After the conclusion of the deprecation period of six months, the API will no longer be available. Any requests after the Sunset date will receive a “HTTP 410 – Gone” response.
Over time, data objects and fields in the Standard Data Model are subject to change. The ‘single source of truth’ for the Standard Data Model is a Git repository.
The key documents that are subject to versioning changes are:
- Mapping files which convert SOH to Data Modelled payloads
- JSON Schema files which describe the fields that make up an entity e.g. vehicle, person, incident
As with API versioning, changes to the Standard Data Model will be accounted for using semantic versioning. These are issued through new Git tags that follow the below convention:
- v1.1.4
A common scenario will be a change to an entity within the standard data model, for example adding a new field. When a small change is made, it will be inappropriate to increment the git tag version and regenerate all the mapping files. The preferable scenario is to regenerate only the mapping file affected.
Where there are external consumers of the Standard Data Model, changes to the payloads will be documented via release notes. These will be issued by the SOH service management team through predefined email templates sent to subscribers of the service.
It is possible that CV list values may need to vary from form to form on SOH. To plan for this scenario, CV lists can be independently versioned.
The ‘single source of truth’ for a CV list field are CSV files stored within the Stoplight Data Modelling platform, which are used to generate JSON schema files containing the values of the CSV files as the possible enumerated values. By including version numbers within CSV file names using semantic versioning, different versions of the same CV list value can be used and referenced by data model objects.
For full details on Standard Data Model versioning, please see section 3 of the iHub Versioning Strategy documentation.
For full details on Single Online Home versioning, please see section 4 of the iHub Versioning Strategy documentation.