...
Following the pilot, we will align the versioning of the semantics with the public versioning of the apis and keep them in step going forward. In the meantime, a change log (manifest) will be used to tie the versions of the semantics and the apis together.
Breaking Changes
In API development, a breaking change refers to modifications in the API that are incompatible with the existing version, potentially causing existing users of the API to experience problems unless they adapt their code. These changes typically require clients to make corresponding updates to maintain functionality. Key examples of breaking changes include:
Removing or Renaming Endpoints: If an API endpoint is removed or renamed, client applications that rely on that endpoint will fail unless updated.
Changing the Behavior of an Endpoint: Altering how an endpoint functions, such as changing its intended effects or outputs, without a corresponding change in the endpoint's name or parameters.
Modifying the Request Format: Changes in how data should be sent to the API, like altering the structure of a request body or the type and name of request parameters.
Altering the Response Format: Changing the structure or format of the response that the API returns, such as removing, renaming, or changing the type of data fields.
Changing Error Codes or Messages: Modifying the error codes or messages returned by the API can affect client application logic that relies on these for handling API errors.
Changing Authentication Requirements: Any modifications in the authentication mechanism or its requirements, like changing from basic authentication to OAuth, would be a breaking change.
Deprecating Features without a Grace Period: Deprecating or removing features without providing adequate notice or a transition period can disrupt client applications.
Changing
...
the Domain or Protocol: Moving the API to a different domain or changing the communication protocol (e.g., from HTTP to HTTPS) without maintaining the old endpoint.
It's crucial for API developers to communicate these changes effectively to users and, where possible, to maintain backward compatibility or provide a transition period to minimize disruption. This often involves versioning the API so that the older version remains operational while clients adapt to the new version.
Release Timing
Breaking or major changes must be coordinated with the community and should only be made on a periodic basis (e.g. once / year). Minor changes and patches may occur at the discretion of the Match-Connect implementation team, with an aim towards continuous delivery.
...