AM-API evolution

AM-API is a consistent, dependable interface for Customers and the foundation of its evolution is minimizing the needs for integration changes.

Over time the AM-API will evolve since there will be new functionality added, existing functionality extended or legacy functionality removed.

Communication of changes

Upon every NET2GRID Insight Platform release that includes changes in AM-API there will be a new post in Changelog section with information about the change.

This information is grouped in the following sections:

• Additions
• Changes
• Support ended
• Discontinued
• Documentation updates

It will be updated promptly to showcase the modifications prior to the deployment on a production environment.

📘

Breaking changes on existing endpoints will be rare

Updates and enhancements of API endpoints will be handled as part of the deprecation process to the extend that this is possible. Removing legacy functionality will also be handled as part of the deprecation process

Deprecation of endpoints

The following process is going to be followed by NET2GRID in case endpoints of the AM-API are going to be deprecated:

1. Announce in changelog the deprecation of an endpoint. This announcement will include instructions on how to migrate from the existing endpoint to the new endpoint (if not legacy functionality that gets removed).
2. The deprecated endpoint will be visible under the "Deprecated" category in API reference. Endpoints under this category are not going to be actively supported any more but they will continue to operate until they are discontinued.
3. 6 months after the announcement of the deprecation, the deprecated endpoint will be discontinued and completely removed from the AM-API.
4. The section that describes the migration process will be removed from the Deprecation section once it is not relevant for any of the customers.

Breaking VS Minor changes

Breaking changes are considered changes that can potentially break the functionality or compatibility of existing client applications. Breaking changes are changes in the schema of the request or response of an endpoint and can include:

• Endpoint removal
• Change in request/response structure like:
  • Deleting an existing query parameter, argument, field or enumeration
  • Adding a new required argument to an existing query or schema
  • Making an optional field required
  • Changing the default value of an optional argument
  • Changing the type of an existing field or return value
• Change in the business logic
• Change in authentication/authorization mechanisms

Minor changes are the ones that have no impact in existing client integrations. For example:

• Adding a new query parameter or enumeration value
• Adding a new optional argument or field
• Adding a new value to an enumeration field
• Adding a new error code in the expected error codes of an endpoint