API versioning plan

[staplegun]

Define and implement the API release versioning strategy.

• Major/minor/patch - https://semver.org/
• How the API server code supports multiple simultaneous versions
• Process for deploying new versions - dev/test/production
• How API clients request particular versions

[staplegun]

Versioning strategy

Follow Semantic Versioning with 'two dots': major.minor.patch

• Major version - Incompatible API changes, e.g. some structured content in a field removed, whole field removed, field structure changed (e.g. from String to Array)
• Minor version - Add functionality in a backwards-compatible manner, e.g. additional structured content in fields, additional fields, additional endpoint/parameters
• Patch version - Backwards-compatible bug fixes, e.g. internal fix that doesn't affect data

API version development and release

Aim: Reduce the number of different versions to be maintained in parallel.

• API software is developed at the major level only, i.e. v0, v1, etc. - the software state reflects the most recent minor version
• API consumers can request at a major level only, i.e. v0, v1, etc. - the API will return the state of the most recent minor version
• If API consumers do not state a version, the most recent version is returned
• Minor and Patch versions are primarily used to track changes in the software and deployment
• A maximum of three major versions are supported in parallel (current plus up to two previous)

Example: An API call requesting v2.4.3 will return the most recent version 2, which might actually be a later minor release v2.5.1

Versioning implementation

• The initial implementation assumes that the CIDOC-CRM model is fairly stable so version variability is supported only in the simple data format
• Multiple JSON blobs are stored in Solr for each version, e.g. simple-v0, simple-v1. The shim extracts the appropriate JSON from the Solr record based on the version requested by the API consumer
• Single search index fields in Solr service queries for all versions
• If/when it is impossible to accurately support the different requirements for each version in searching or RDF records, then at that point the architecture will be extended to support multiple versions

Code changes

• Separate XSL mappings for each version, e.g. trix-description-to-dc-v1.xsl, trix-description-to-dc-v2.xsl
• New XProc stage that combines the Solr search fields, multiple simple version data formats, and the json-ld data format into a single Solr record for loading
• Shim supports version content negotiation - for displaying a single resource or query results

[staplegun]

API content negotiation for version

• Version requesting is only possible via an HTTP header (no equivalent URL parameter is supported)
• Version requesting is optional (the API defaults to the most recent version), so it is only necessary if requesting a previous version

JSON-LD

• Use the profile parameter in the JSON-LD specification
• The profile value must be a URI (not IRI) and be quoted
• It is recommended that the URI is dereferenceable and provide useful information
• Example: Accept: application/ld+json; profile="http://data.nma.gov.au/term/collection-api-version-0"

JSON

• Use a vendor type rather than the usual application/json - See: RESTFul API Versioning Insights
• Example: Accept: application/vnd.nma.collection.api.v1+json
• Or x version (vnd should eventually be registered): Accept: application/x.nma.collection.api.v1+json

The API response should include the version being delivered

• Example: ContentType: application/vnd.nma.collection.api.v1+json