Version Stability, Breaking Changes, and Deprecation Policy

The public APIs for ManageBac+, OpenApply, and Atlas are being continuously improved to enable customers, partners, and consultants to unlock and extend our range of products. In order to ensure that the systems that depend on the public APIs remain stable and reliable, Faria Education Group adheres to the principles outlined in this guide when planning and developing our RESTful Public APIs.

Backward Compatibility

Our API now supports versioning, giving development teams the flexibility to choose between stability and rapid access to new features. Teams can explicitly target a stable version to ensure consistency and minimize disruptions, or opt into the latest version to automatically benefit from the newest enhancements and improvements as they are released. This approach empowers developers to align their integration strategy with their project’s tolerance for change and need for innovation.

Non-breaking Changes

Changes that we may make, which we do not consider to be a breaking change — and thus do not require provisioning a new version or "version bump" —are the following improvements or additions:

• New Endpoints. For example adding a new endpoint will immediately be available upon release in latest version, but not included in stable versions.

• Adding new fields to response objects. Code should be able to gracefully handle new fields being added to response objects without raising exceptions.

• Changing default values of parameters. The most common parameter whose default value that may be changed is the meta.per_page parameter. For example, the per_page parameter's default value may be published as 50, but if load optimizations require it, it may be changed to a lower number, such as 10. In this case, it is not considered a breaking change since the response itself gives the actual value applied, and code should rely on the value in the response rather than the request.

• Adding optional parameters. We may add parameters that assist with filtering records.

• Changing error messages. As we improve our understanding of how external systems use our APIs, we may change the error messages to improve debugging and troubleshooting. For example, the messages may become more verbose or the wording may be adjusted for clarity. The values of error messages are intended for the developer interacting with the endpoint, rather than to be relied upon to be parsed or machine-read.

Breaking Changes

The following are examples that would require a version bump:

• Removing an endpoint entirely

• Adding a required query parameter to an endpoint

• Removing or renaming a field in a response object

• Introducing inconsistent response objects

• Changing the structure of a response object

Deprecation Notice

When individual endpoints or entire versions need to be deprecated, this information will be pushlished and released.

In that case, the following will happen:

• We will publish the deprecation in the change log, three months in advance of the intended sunset date

• We will reach out to partners through internal channels

About Versioning