Skip to main content

Change Policy

Types of change​

As the Informed API improves and expands over time, change is inevitable. Informed categorizes these changes in one of two ways:

Non-breaking changes​

Informed may implement non-breaking changes to any of the endpoints at any time, with no advance notice.  As such, it is imperative that you design your integration of the Informed API to handle any of the non-breaking changes.

Examples of non-breaking (backwards-compatible) changes on the request side:

  • New, non-required query parameters can be added to the request.
  • New, non-required properties can be added to the body of the request payload.
  • Requests are compatible regardless of the order of the query parameters or the order of the properties in the body of the request payload.
  • Adding new API resources / endpoints.
  • There is no guarantee that the file upload URL's (typically AWS S3 pre-signed URL's) will remain exactly the same for all future time. Informed reserves the right to use whatever infrastructure is most secure and efficient.

Examples of non-breaking (backwards-compatible) changes on the response side:

  • New properties may be added to the response.
  • Properties with null values may be ommitted from responses, the corollary of which is that any string or numeric value can also be a null value.
  • The order of properties in the response is not fixed or guaranteed.
  • Changing the format of human-readable messages or other opaque strings, such as object ID's, error messages, descriptions, recommendations, etc.
  • Adding new event types.
  • Adding valid items to the list of acceptable values for enumerated fields in the responses.
  • There is no guarantee that the file download URL's (typically AWS S3 pre-signed URL's) will remain exactly the same for all future time. Informed reserves the right to use whatever infrastructure is most secure and efficient.

Breaking changes​

warning

This breaking change section is specifically focused on the production environment. There may be brief time periods when the staging (non-production) environment is used to test new features that will be out of sync with production. If you experience issues on staging, you are highly encouraged to report them, however these will not be considered breaking changes from a production perspective.

If Informed introduces a signifcant enough change that it is considered a breaking change, then Informed will increase the version number used in the path of the resource being requested.

Informed will provide advance notice of breaking changes as well as a timeline and migration path for transition to the new version of the endpoint involved.

Examples of breaking changes:

  • Adding required request parameters or request body fields to an existing API request.
  • Removing request parameters or request body fields from an existing API request.
  • Removing critically relevant properties from existing API responses.
  • Removing valid items from the list of acceptable values for enumerated fields in existing API responses.
  • Removing an existing API resource / endpoint.