Scehma Versioning of Event driven architecture
What are some ways schema versioning is done.
Currently at work our system has no schema versioning, so I have been working on a middle man module that will be the start of versioning everything at least externally. With that comes schema versioning and a rest api that functions over an event based backend. The most obvious first step is adding a schema version, our api will be v1/<resource>.
However, there can be minor schema changes and additions, and I am not sure on how to best go about handling this.
Should each backend module have a registery of schemas, and what version a field is supported?
Should I have a mapper to map between old and new versions of the schema when they are minor updates?
The biggest thing is keeping a consistent rest api, but allowing us to make heavy handed backend changes, I presume as long as the fields stay the same or relatively the same this shouldn't be too bad as we work to update our existing architecture. Any thoughts or recomended readings/research topics would help, as I am getting a bit of information overload.
3 Replies
- Minor changes don't need versioning. If
/foos starts returning a new fooName value, it doesn't break anyone. But if fooName is renamed to fooFirstName then that breaks everyone using it. (keep both instead)
- Strive to make backward-compatible changes as much as possible. You can absolutely gut the inner working as much as you want but inputs and outputs should be kept consistent for everyone's sanity. Add new ones, don't remove or change existing ones. Mark old ones as deprecated in any docs but keep supporting them indefinitely.
- If you absolutely must break backward compatibility then it's time to update the version and url (think SemVer major version bump). This gets painful - you basically do end up with 2 totally separate endpoints doing relatively similar jobs. Having reusable functions helps. But you'll want to put a plan in place to help all your users migrate so you're not maintaining both forever.
- Keep in mind some users may use v3/foos with v1/bars. This should be fine cause the version is the endpoint/model, not the service. There might not even be a v3/bars yet. But it does cause confusion sometimes.Ah perfect then, this was along the lines of what I was expecting, I figured major version changes would be major schema overhauls.
The API schema is roughly the inputs and outputs (and their types and what's required/optional, etc). Changing those is where things will break and where OP was uncertain of how to keep up with the necessary changes.