API maturity
API maturity ratings
Each of the STARS core business scenarios and specific API endpoints has a maturity rating:
Understanding API maturity
What do maturity levels mean and how do I use them?
API maturity levels help you make informed decisions about how much effort to invest in building features that depend on a given API. Each level indicates how stable, complete, and well‑defined the API is, and therefore how much change you should expect.
API maturity is defined across six levels, representing the full lifecycle of an API. As we work towards go‑live, the first three levels are the most relevant.
Designed - Enable preview, consultation and feedback
Experimental - Validate concepts, review specifications, build refinements
Release candidate - Final validation before production, subject to versioning
General availability - Live, supported production service
Deprecated - Managed transition away
Retired - Endpoint no longer available
Additional context and caveats are provided for Designed, Experimental, and Release candidate APIs. This information is critical for planning development activities during these stages.
For example, when developing against an Experimental API, we may indicate that a future release will introduce an additional search parameter to better identify failed validation results from synchronously executed validation rules allowing you to plan workflow improvements while minimizing rework.
What developers should do with Designed, Experimental, and Release candidate APIs
Designed APIs
Designed APIs support early consultation and feedback with SMS suppliers, state training authorities (STAs), and other stakeholders involved in ongoing VET IS development. At this stage, the API represents an initial design that is expected to change significantly based on feedback and evolving requirements.
Provide feedback on model and semantics
Use mocks, stubs or explore API sequences
Experimental APIs
Experimental APIs support active design, development, and testing. You can begin implementation work against APIs at this level, including integration testing.
The provided details highlight any caveats you should consider so you can plan effectively and minimize rework. Indirect Jurisdictions are also expected to begin developing their systems during this stage.
Change is still possible, including updates to contracts, behaviours, and domain rules.
Build real integrations. If these are part of your core code base make sure these are behind feature flags.
Expect breaking changes without version bumps
Release candidate APIs
Release candidate APIs are expected to be largely stable. Changes should be minimal and limited to critical fixes.
At this stage:
API interfaces and contracts should not change for most criteria
Comple integration and acceptance testing
Perform security and performance testing
The API should be considered production‑ready pending final approval
Remember to treat scenarios as your primary contract
Rather than integrating individual endpoints in isolation:
Identify the scenarios you depend on
Track the maturity of each scenario, not just the endpoints
Assume a scenario’s stability is limited by its least mature route
If any route in a scenario is Designed or Experimental, the entire scenario should be treated as unstable.
How scenario stability is described (for levels 1-3)
API endpoints on their own aren't particularly useful. It's only when those endpoints can be used in a workflow to achieve a business outcome that they provide value. For APIs in the Designed, Experimental, and Release candidate stages scenarios are assessed for maturity using the following characteristics:
API endpoint maturity
The lowest maturity of any route and verb used in this scenario.
Note that
A scenario cannot be more mature than its least‑mature endpoint
One unstable edge case endpoint can downgrade the whole workflow
Technical scenario completeness
How complete, well described and stable scenarios describing API sequencing and system behaviour are. Core technical scenarios are provided with variations adjacent to that where there's specific behaviour you need to be aware of. For example, in the Upload of the minimal unit record for a Subject Enrolment the first submission is the core workflow but we describe the subsequent submission showing that related resources should not be uploaded unless there's a change.
Business outcomes and documentation completeness
How complete and well‑described the business outcomes are, and how comprehensive the documentation is in supporting the achievement of those outcomes. These are described by end-to-end scenarios made from several technical scenarios.
For example, Declarations describes which activities should be completed before performing a declaration and the conditions under which to perform the different kinds of declaration.
How endpoint stability is described (for levels 1–3)
For APIs in the Designed, Experimental, and Release candidate stages, each endpoint documents the following stability characteristics:
Interface stability
Describes whether routes, HTTP verbs, and resources may change, and under what circumstances.
Contract stability
Describes whether request/response schemas may change, including field additions, removals, or modifications.
Value stability
Describes whether enumerated values, reference data, or data formats may change. This includes query parameters - which are not assessed as part of the interface.
Behaviour stability
Describes whether system behaviour may change despite interface and contract stability.
For example:
Business rules may change
API sequencing requirements may change
Different domain validation errors may be returned
Scenarios
Describes the level of coverage for:
Technical scenarios (system behaviour and sequencing)
End‑to‑end business scenarios (business processes supported)
A single endpoint is often used across multiple technical and business scenarios.
Change strategy
Describes how breaking or significant changes are managed:
Whether changes may occur within the current API version
Or whether significant changes will result in a new version
Our goal is to keep disruptive changes constrained to the Designed maturity level. However, changes to the current version may still occur based on developer feedback and issues identified during development. New major versions are introduced only when necessary to manage breaking changes.
Generally available APIs and the change strategy
Once APIs become generally available non-breaking changes will be made to the same API version. More disruptive changes will be introduced by creating replacement APIs, deprecation of APIs and eventual retirement of those APIs over an extended timeframe within the same version.
Breaking changes that cannot be gradually introduced into the same version will result in a second version of the API being created. The old version will be maintained for compatibility with older clients to provide time to switch.