Versioning

Minor updates and bug fixes are implemented continuously and preserve existing API behavior. Significant updates that alter API behavior are released to a new URL leveraging versioning, for example https://sfoptapi.com/{apiVersion}/routing where {apiVersion} might be v1, v2, v3 and so on. The CHANGELOG tracks all changes made to the APIs. Changes that are considered backward compatible:

• Changing a parameter from required to optional
• Adding enumeration values
• Adding new functionality

API versions are embedded in the URL to ensure that releases do not create a breaking change. For example, in the release from v1 to v2, clients on v1 are not affected because the URL to v1 is still valid and consistent with the v1 specifications.

When a legacy API version reaches its end-of-life and will no longer be accessible, all users are notified 90 days in-advance to ensure that applications update to a newer API version. Also, requests to retired API versions receive a default error response with a 30x status code and message pointing to the latest version of that API.

Our documentation is built using the OpenAPI Specification, and the full spec for each API is available at the top of the API's docs page via the "Download" button. We encourage others to continue support of the OpenAPI Initiative to ensure harmonization among the universe of API's.