Handling Core releases
Handling Core releases
Being adaptive to changeOur goal is to make you adaptive to change. Whether it's webservices for building integrations, run front ends or fetch information, EVA's thousands of webservices have to change on a weekly basis. This means we might add new fields, change logic, settings or remove legacy, all to ensure we offer the best solution out there and to keep you ahead of the curve.
Deprecations
We call these changes deprecations and they are important to keep track of. Changing fields might impact integrations you have built using our APIs, which is why each change to an API gets announced in advance - and we are very careful about removing logic.
The same goes for the settings by which you configure your environment: these can become deprecated when they are superseded by new or improved processes. Most commonly, these would be “Temporary Feature Flags”, which had been introduced to allow disabling a new feature in case it shows unintended side-effects (opt-out), or the other way around, which would allow enabling a new feature (opt-in) before it becomes the default.
Warnings
API changes
When changes are introduced to your environment (phase 1), these changes will show up in your typings and will generate EVA-Warning
headers in response to you using them. Be sure you always catch and log these warnings, and take action accordingly.
Eventually (phase 2), deprecated services and properties will no longer show up in typings, and phased-in requirements will be marked as such. This will impede your development, but do not break your application.
Phase 2 is our final warning before the changes become effective, because the next step (phase 3) is to actively enforce these changes:
- using deprecated services will yield a
404 NOT FOUND
response; - using deprecated properties or omitting required properties yields a
400 BAD REQUEST
response.
Settings changes
Just like with services, deprecations to settings follow 3 stages, which we've fixed on an impact of Highest (32) and thus each stage transitions in 32 releases:
- Communication: when introduced, deprecated settings will be communicated as such through release notes, deprecation logs, dashboards and in Admin Suite
- Default value switch: after 32 weeks we hit phase 1 (typings), where we will start to default to the new desired value - this means the opt-in features will then automatically enable but any explicit value configured will remain unaffected
- Default value enforce: after another 32 weeks we hit stage 2 (effective), where we will enforce the desired value, ignoring any configured values
For API changes as well as settings goes that we're a little more lenient on Production environments. We won't actively enforce, but as we refactor old code, support could be dropped completely without any further warning or notice.
Where to find information?
With thousands of annual changes and additions to our APIs it’s not doable for a customer to wade through endless changelogs. That’s why we also offer contextual warnings.
Total overview
It's a lot - so this is not advised. But for those who like reading: this URL contains all EVA APIs and changes:
https://api.euw.YOURENDPOINTNAME.test.eva-online.cloud/api/changes
Response headers
For each call you do to an EVA service, you get a response. In the header of this response there is a section called EVA-Warning
. Whenever there are pending changes impacting this particular API they are communicated here.
You can log this data on your end to create a contextual dashboard of changes to APIs relevant to your landscape.
Integration dashboard
As an alternative to a dashboard maintained by you, we also offer an out of the box integration dashboard. This dashboard (ask your Transformation Lead for the URL) contains a contextual view of all APIs you interact with, plus whichever deprecation warnings are relevant.
Release notes
The weekly release of our Core includes all changes to APIs and settings. These are explained in our Drop Notes. Note: the purpose of these drop notes is mainly to document new services or fields. For true deprecations, the routes described above are your best bet.
EVA Typings
Our various SDKs provide schemas and declarations that are very beneficial to tracking down where you might be using deprecated features. If you are using the TypeScript SDK, warnings will automatically be logged as warnings to your console. You will want to keep an eye on these.
When are changes communicated?
We've divided the possible impact of changes into five different categories - from Lowest to Highest. Each category comes with its own predetermined amount of time that we will notify you before the change comes into effect.
Taking a look at the table with the categories, you can see how a Low impact deprecation would be announced in headers 4 weeks before it would be removed from typings and take effect on your Test environment. After that, there would be another 4 weeks before the deprecations are introduced on a Production environment.
This means you have 8 weeks between the initial announcement of this Low impact change, and the first moment deprecations might impact your Production set-up.
For truly impactful changes, this total window is over a year: 64 (32 + 32) weeks.
Impact | Description | Weeks |
---|---|---|
Lowest | No action is expected from any app. | 2 (+2) |
Low | Simple property rename. | 4 (+4) |
Medium | Different property setup, simple service rename. | 8 (+8) |
High | Different service setup, service chain changes. | 16 (+16) |
Highest | Global service changes. | 32 (+32) |
How to interpret information?
- Each weekly core release has a release number. For example:
Core 2.0.650
. - Every new weekly Core release, the number increased by +1.
- Deprecation announcements mention when a field/service is deprecated using this release numbering.
- EVA API response always contains the current release number in the EVA-Version field.
So if your current release is 2.0.650, and we announce a deprecation takes effect in 2.0.682 then you know it is a Highest impact deprecation. After 2.0.682 you would have another 32 weeks before impacting Production environments - 2.0.714.
So when (first) seeing a deprecation announcement: check how many weeks after your current week it takes effect to prioritise any changes.