Lumirank Versioning
Which changes can happen inside v1, which ones need a new version, and how to write code that keeps working.
The version is part of the path: /v1. A new version comes only with a change that could break your code.
Changes that can happen inside v1
These changes can be added to v1 at any time. The changelog lists each one:
- a new endpoint;
- a new optional parameter;
- a new field in a response;
- a new allowed value for a field, for example a new engine;
- a new error code;
- a new report dimension or metric.
Changes that need a new version
These changes come only in /v2:
- removing or renaming a field;
- changing a field's type or meaning;
- a new required parameter;
- a different default value.
After v2 is released, v1 keeps working for at least 12 months. The changelog gives the date v1 stops, and the people who own keys get an email about it.
Write code that keeps working
- Ignore response fields you do not know.
- If a field has a value you do not know, for example a new engine, handle it as "other".
- If you get an error code you do not know, handle it by its HTTP status.