Handling Core releases

Our 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 the EVA 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

Deprecations on production environments

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.

Deprecator 2000

Want to look for deprecations impacting a particular service in EVA? Visit Deprecator 2000 and look for your API to see deprecations.

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?

As a reference for the estimated impact of a change, we've annotated each of them, roughly following below guidelines. The number between brackets is the number of weeks between each phase.

So a Low impact deprecation will be announced in headers 4 weeks before it is removed from typings and take effect on your Test environment. After that, there is a 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 weeks.

Impact	Description	Weeks
Lowest	No action is expected from any app.	2
Low	Simple property rename.	4
Medium	Different property setup, simple service rename.	8
High	Different service setup, service chain changes.	16
Highest	Global service changes.	32

How to interpret information?

• Each weekly core release has a release number. Example: Core 2.0.650.
• Every new weekly release, the number increased by +1
• Deprecation announcements mention when a field/service is deprecated using this release numbering.
• EVA API responses always contain your 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 32 weeks from now.

So when (first) seeing a deprecation announcement: check how many weeks after your current week it takes effect to prioritise any changes.