U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

FAC API versioning

This page describes how the FAC API will change over time, how those changes will be communicated, and how to understand the FAC APIs naming conventions. On October 1, 2023, these conventions will become operating procedure.

API naming conventions

For example:

Offering multiple API versions in parallel

The FAC API can provide multiple versions of the API at the same time using PostgREST's schema functionality. A full list of available schemas will be documented here as they become available.

While you can specify a particular schema when making a request, If you don't specify a particular API version in your request, the FAC API defaults to the most recent stable version. See the PostgREST schema documenation for guidance on specifying a version in your request.

For example, if the FAC API theoretically supported the versions v1.1.0, v2.0.0, v3.0.0-beta:

Bugfixes and pre-releases

There may be some instances in which the most recent SemVer release is not the default for its MAJOR release. For example, we may opt to run a short test to confirm that a bug is fixed before making a particular release the default. This should be rare and is unlikely to impact regular API users.

You should not assume that a particular pre-release version will be available for any amount of time. They are intended primarily for testing and will likely rotate through the list of releases quickly.

Migrating to new versions

Prior to a MAJOR release, we will publish a rough release timeline to help the community prepare for any breaking changes. Once an early prerelease version is ready, we will make an announcement and seek test volunteers from our user community.

When we're confident in a new version of the API, we will announce the new version as a non-default, opt-in version for more users. We'll also post when the new version will become the default (e.g. T+3 months). During this period, users can opt-in to using this new version to ensure their processes will still work before it becomes the default.

Once a new version becomes the default, we'll announce the date that the older version will be removed from service (e.g. T+12 months). Users will still be able to use the deprecated version by request until the removal date.

Our goal with this process is to ensure that users aren't rushed into migrating new versions and have ample time to prepare. At the same time, we can't commit to supporting old APIs indefinitely.

This process will apply to all changes to the API, both MAJOR and MINOR.