English

Italiano

English

Italiano

Appearance

Change management ​

This page describes how API evolution is managed over time and how to design a resilient client.

Stability and compatibility ​

APIs are designed to ensure stability for existing integrations:

  • existing fields are not removed;
  • published fields are not changed in a breaking way;
  • HTTP status codes for the same conditions are not changed;
  • endpoints already in use are not renamed.

A working integration continues to work with new backend versions.

Additive changes ​

Additive changes may be introduced without notice, for example:

  • new fields in responses;
  • new optional values;
  • new properties in existing objects;
  • new endpoints.

Concrete example ​

Today a patient response might have this structure:

json
{
  "id": 123,
  "firstName": "Mario",
  "lastName": "Rossi",
  "fiscalCode": "RSSMRA80A01H501Z"
}

Tomorrow the same response might include a new field:

json
{
  "id": 123,
  "firstName": "Mario",
  "lastName": "Rossi",
  "fiscalCode": "RSSMRA80A01H501Z",
  "middleName": null
}

This is not a breaking change: the field was added, no existing field was changed.

How to design a resilient client ​

To handle additive changes correctly:

  • do not assume the response contains only the fields documented today — there may be more tomorrow;
  • safely ignore unrecognized fields — your JSON parser must not fail on unknown properties;
  • validate only the fields your logic actually needs, not the entire response structure;
  • do not compare the full JSON response rigidly (e.g. with hash or exact equality) to detect changes.

💡 Deserializer setting

Most modern JSON frameworks ignore unknown properties by default (e.g. System.Text.Json in .NET, Jackson in Java, json in Python). Ensure this setting is active in your client.

Deprecations and notifications ​

When an API is deprecated:

  1. Notification is sent to the email of the account that registered the OAuth application.
  2. A reasonable transition period is given before definitive removal.
  3. Documentation is updated to mark the deprecated endpoint and indicate the alternative, if available.

For this reason it is recommended to use as reference an account that is:

  • not personal (e.g. team mailbox), or
  • reachable over time even if people or roles change.

⚠️ Note

Do not monitor deprecations manually: ensure the mailbox associated with the OAuth application is read regularly.

Next steps ​