Release 4 (R4) release notes
Release 4 (R4) enables SMS suppliers to start developing integration with STARS.
Several business outcomes are sufficiently supported by stable APIs and related documentation to build against. See API maturity to understand which outcomes and scenarios are supported, along with caveats and possible changes.
1. Changes to routes
Further planning for future needs has resulted in some changes to route prefixes for the published APIs as well as improved naming and descriptions.
For example, the Client Integration (Docs) API was published under the name STARS VET Provider Collection API (Docs) with a route prefix of /cin-docs. In this release the same API will be published under the name STARS Vet Provider API – Client Integration V1 (Docs) with a route prefix of /cin/docs/vet-provider/v1 and includes a description. Note that the vet-provider/v1 part of the URL has not changed but is now included in the prefix rather than part of the API route.
You will need to check the route prefixes you have been using and the leading part of the route described in the OpenAPI specification as this has moved to the prefix.
The next release will introduce historical OpenAPI specifications so that previous release’s API specifications can be downloaded for informational needs and change identification via comparison tools.
2. Availability of functional system
A functional version of STARS is available in R5 under the STARS VET Provider Collection API – Client Integration V1. The system will enable you to commence development and testing capabilities delivering on several business outcomes.
This environment has been provisioned with low tier infrastructure. As a result, performance will not be high. This will be scaled up as required based on SMS supplier needs. However, we don’t intend for performance testing to be conducted in this environment at this stage.
Also note that calls to /validate and /submit on a transaction batch will take longer than intended and don’t demonstrate the behaviour of the final system – in this release, these actions are processed sequentially on a single queue. Please take this into consideration when developing and testing these functions.
Specific details of each endpoint are described in the API maturity documentation.
3. API maturity
API maturity is documented on the developer portal to provide insight into how complete our documentation describing business objectives and technical scenarios to achieve those objectives is.
API maturity provides insight down to the route and verb, enabling visibility of upcoming and planned changes including any caveats and suggestions.
Use the API maturity to make informed decisions on how to progress with development and testing. The business objectives and technical scenarios call out specific features, which can be built and tested.
Refer to the API maturity documentation to understand and plan which capabilities to start developing and testing.
4. Support for compressed payloads enabled
Support for compressed payloads has been enabled and the maximum (compressed) payload size set to 1 MiB (1,048,576 bytes). The supported compression algorithms are gzip, br and deflate.
Future releases are planning to enforce compression. However, this has not been implemented in this release.
Uncompressed payloads are limited to 1 MiB.
Configure clients to send compressed payloads as soon as practicable as this will be enforced in a future release.
5. Submit valid data outcome
The core workflow for submit valid data can be developed against. Details of the business outcome, core technical scenarios and details on validation rules are provided.
Use the minimal unit record in the technical scenarios and the STARS rules catalogue to start building out the “Upload” technical scenario and mapping your domain model to the STARS transport model. The minimal unit record can be used piecemeal and replaced with entities from your system as you map and transform to each top-level resource.
6. Problem details API contracts
All non-default status or error responses have been replaced. Expected non-default status codes have been assigned a well-defined schema based on an extended RFC 9457 problem details. These changes are representative of the final structure of problem details records in STARS. Minor enhancements will continue.
In R3 the response contract represented a basic RFC 9457 but did not include details about the extensions used under different conditions. Generated contracts would not include the details returned by the API.
All well defined problem details include a technical rule id which can be looked up in the STARS rule catalogue and a trace id which should be logged and provided to support to assist in troubleshooting. Additional details are included for each status code as required.
The 400 bad request ValidationErrorProblemDetails is used to represent request payload and system state errors. This provides a machine-readable method for handling the specific error conditions a client is going to need to support when interacting with STARS. Where possible individual technical rule id’s have been assigned to allow programmatic handling of specific error conditions – message text should not be used for determining the specific error. Request payload validation uses a collection of errors representing the structure of the content with a message about the failure.
Update all error handling code to leverage the structurally correct problem details and use the technical rule id to determine corrective actions.
Some protocol errors are not assigned specific contracts but may be encountered. The ProblemDetails contracts represent expected errors.
Some status codes could be used by other services in the pipeline. For example, 413 Content Too Large can be returned by the STARS API’s or an upstream component like Azure API Management.
7. VET IS API contract changes
The Student top-level resource secondarySchoolType attribute has been changed to a flag. This was done to align with changes to the draft VET Information Standard.
This is a breaking change. Remove all references to secondary school type and map Yes_enrolled_in_school to true and No_not_enrolled_in_school to false.
8. Other noteworthy contract changes
Declarations endpoints have been built out further to include a GET for searching and declaration types. Declarations endpoints are continuing to be enhanced. See API maturity and declarations objectives.
The ProblemDetailsError approach significantly changes the non-default response contracts for all APIs. Refer to the Problem Details API contracts section above for more information.
Access path has changed from a string to an array of strings. Refer to the documentation on access path to understand the data format. Given the format is complex it’s best to consult the documentation before building against the value.
9. Developer portal content
The developer portal content has been significantly updated to support SMS suppliers beginning development while improving content for planning your delivery approach.
Some content has been arranged to provide a better flow through topics. This means top level headings have changed, and some content will have been moved to a new location. Some links directly to content might still work but redirects were not added for moved content.
10. Maintenance on stubs
Stubs endpoints and Bruno files have been updated with changes to support the latest release. No additional scenarios have been added.
The Bruno files can be used against the functional endpoints. The scenario key should be stripped off; however, we don’t enforce any rules that prevent it.
11. Known issues
Issue: Client Integration – docs endpoint does not show the latest version of declarations endpoints.
Impact: Downloading designed API’s from the docs endpoint shows an incorrect OpenAPI specification and list of supported API’s.
Workaround: Refer the STARS VET Provider Collection API – Client Integration – V1 API for the most up to date specification.
Status: Open
Issue: Client Integration – The Subject Enrolment Locations Training Venue Type is missing the value Not_applicable.
Impact: The SubjectEnrolment.locations.trainingVenueType (#/components/schemas/Reference.SubjectEnrolmentTrainingVenueType) is not shown as an allowed value. This does not affect any validation rules in R4. However, some types of SubjectEnrolment.locations require Not_applicable to be represented correctly. These types of Subject Enrolment location cannot be mapped in the current release. Some Not Implemented STARS rules (scheduled for R5) require this field.
Workaround: Do not map locations with a Location Usage Type of Subject_delivery_location, Training Venue Type of Not_applicable and Delivery Location UID till R5. All other locations can be mapped correctly.
Issue: Client Integration – Asynchronous Validation and Submission taking longer than 30 seconds will fail and is not retried
Impact: Larger transaction batches, or small transaction batches doing updates affecting large amounts of previously submitted data cannot be validated. These transaction batches will not finish validating and cannot be submitted.
Workaround: Ensure transaction batches are small. The environment is not currently configured to support load testing or testing with large volumes of data. This will be enabled in a later release.
If a transaction batch takes an excessively long period to complete validation or submission, a timeout may have occurred. Create a new transaction batch and ignore the stuck transaction batch. If the issue occurs consistently contact support with the transaction batch token and any relevant traceId’s
Issue: Client Integration – Transaction batch state transitions are not checked correctly when submitting a transaction batch with validation status of InProgress.
Impact: Submit should not be called until validation is completed. However, if you call submit while the validation status is in progress the request is accepted and the transaction batch cannot be submitted.
Workaround: Following the documented process of checking the validate asynchronous task has completed and there are no blocking validation failures before calling submit will not result in an issue. If a transaction batch has been submitted while validation is in progress create a new transaction batch and ignore the stuck transaction batch.