Versioning
What can change within v1, and how breaking changes are announced.
The major version is in the address: /v1. The contract's revision is 1.2.0; it goes up with each published change, and the changelog lists each one.
Changes within v1
v1 grows only by adding. It can add paths, operations, fields, values and error codes without notice, so:
- Ignore fields you do not know.
- Fields that list values, such as
outcome,statusandrequirement, are open: new values can appear. Treat an outcome you do not know as needing review, not as completed. - Handle an error code you do not know by its HTTP status.
Breaking changes
Removing a path, an operation, a response field or an error code, or making a field required, would break clients. Changes like these come only with a new major version, /v2, announced at least 12 months ahead, here and in the changelog.
Follow changes
- The changelog, also as an RSS feed.
- The contract at
https://api.kapiworks.com/v1/openapi.json, to compare one revision with the next.