Versioning

API Versioning

In general, Pearl adheres to the belief that “an API is a contract.” and will endeavor to not make surprising changes within the same version of an API, and will use Semantic Versioning(semver) as a guideline. That said, as a small, agile organization, Pearl frequently updates the Pearl Software and seeks to balance the tension between an overly cumbersome collection of concurrently-supported API versions on the one hand, and requiring constant updates from customers and clients on the other. Therefore, expect the following regarding API versioning:

• A MAJOR version change (1.19.0 -> 2.0.0) will be backwards incompatible in some fashion. We will bump a major version if API parameters are removed for example.
• A MINOR version change (1.19.0 -> 1.20.0) indicates a backwards compatible change. For example, if we add an API parameter.
• PATCH level changes will be rare.

NB: SCORING MAY CHANGE WITHOUT AN API VERSION CHANGE.

Pearl takes the sanctity and accuracy of the Pearl Score very seriously. There are times when anomalies are discovered and must be addressed, or nuances must be explored more thoroughly than previously. Therefore it is possible, however unlikely, that you may request information about a home on one day from the exact same URL and receive a different score than you did when requesting information about the home the previous day. Obviously, Pearl strives to keep these changes to a minimum, but they may occur.

Also note that the title information included in the API documentation is reference information for your convenience. It is based on the UI that Pearl presents as part of the cert app. Those values are also subject to change as Pearl may clarify UI changes more often than it wishes to update the API. While you may use the values therein, it is strongly recommended that you not do hard-coded comparisons against the literal values in the documented titles.

Deprecation Schedule

• Since minor version changes are backwards compatible and small in nature, they should be easily absorbed into your software, therefore Pearl will support previous minor version for up to 3 months after the introduction of the new version. Due to the increased level of effort in uprgading to a new major version of an API, Pearl will support the previous major version for up to 12 months after the introduction of a new major version of the Pearl API.

Current Deprecations

Pearl API Version 6.4.0 was introduced on 2024-04-16. 6.3.0 was introduced on 2024-03-26. 6.3.0 is now deprecated and may be removed after 2024-07-16.

Pearl API Version 5.0.0 was introduced on 2022-08-15. 5.0.0 is now deprecated and may be removed after 2024-02-08.

Pearl API Version 4.0.0 was introduced on 2021-06-28. 4.2.0 was introduced 2021-12-16. All 4.x users should now be on 4.2.0. 4.2.0 is now deprecated and may be removed after 2023-08-15.

All versions before 4.2.0 have already reached End of Life and may disappear without further notice.

See the Changelog for details.

Version Change Criteria