API deprecation policy

Deprecation and breaking change policy

Occasionally the Federal Election Commission (FEC) will decide to deprecate, including making breaking changes to an API endpoint, feature, or service. An endpoint, feature, or service that has been deprecated will eventually be removed entirely, introducing a breaking change. In some cases, a removed endpoint, feature, or service will be replaced by another endpoint, feature, or service. This documentation serves as a guide to handling the cases of an endpoint, feature, or service being:

• Removal of service without replacement, or
• Removal of service with replacement.

Removal of endpoint, feature, or service without replacement

If an endpoint, feature, or service will be deprecated and eventually removed with no replacement:

1. Start with a GitHub issue where completion criteria includes:
   • In the API documentation, add a deprecation description to the endpoint, feature, or service; and
   • Send an email to registered API users who have used the endpoint, feature, or service being deprecated notifying them of the pending deprecation.
2. Add the "deprecated" label to the issue.
3. Explain in the body of the issue why the deprecation is necessary.
4. Open another GitHub issue to remove the endpoint, feature, or service where completion criteria includes:
   • Send an email to registered API users who have used the functionality being deprecated within the last 120 days, notifying them that the endpoint, feature, or service will be removed. Make sure that at least 30 days has passed since the original email advising of the deprecation has been sent.
   • Remove the endpoint, feature, or service no sooner than 30 days since the last email to API users.
   • When feasible, add a helpful error and/or validation message for using the old functionality.
   • Add the "breaking change" label to the issue.

Removal of service with replacement

If an endpoint, feature, or service will be replaced by another endpoint, feature, or service:

1. Start with a GitHub issue where completion criteria includes:
   • In the API documentation, add a deprecation description to the endpoint, feature, or service; and
   • Send an email to registered API users who have used the endpoint, feature, or service being deprecated notifying them of the pending deprecation.
2. Add the "deprecated" label to the issue.
3. Explain in the body of the issue why the deprecation is necessary.
4. Open a GitHub issue to add the replacement endpoint, feature, or service (unless the replacement endpoint, feature or service already exists).
5. Open another GitHub issue to remove the original endpoint, feature, or service where completion criteria include:
   • Send an email to registered API users who have used the functionality being deprecated within the last 120 days, notifying them that the endpoint, feature, or service will be removed. Make sure that at least 30 days has passed since the original email advising of the deprecation has been sent.
   • Remove the endpoint, feature, or service no sooner than 30 days since the last email to API users.
   • When feasible, add a helpful error and/or validation message for using the old functionality.
   • Add the "breaking change" label to the issue.

Here’s an example of a "Deprecated, then replaced, then removed" action:

The FEC determines /ordinary_endpoint/ is not serving customers as well as /improved_endpoint/ will. We have decided to replace /ordinary_endpoint/ entirely with /improved_endpoint/. First, we make /improved_endpoint/ available, for example, on January 1, 2020. Next, we will notify affected registered API users (identified in the API umbrella as users of the endpoint, feature, or service in the last 120 days) of the deprecation, advising them to use /improved_endpoint/ instead. If we want to remove /ordinary_endpoint/ by March 15, 2020, for example, we should make the deprecation notice available by email and in our API by January 15, 2020. An example initial email to our API users:

This email provides information about changes to the Federal Election Commission’s (FEC) API, openFEC. /ordinary_endpoint/ has been deprecated and will be removed after March 15, 2020 and will no longer be available for use. Please use /improved_endpoint/ instead. Should you have any questions, please contact APIinfo@fec.gov. You can also review our deprecation policy for more information. An example endpoint notice: /ordinary_endpoint/ Deprecated. To be removed after March 15, 2020. Please use /improved_endpoint/ instead.

On February 14, 2020, we will send a reminder email containing the same information as the original email. We can shut down access to /ordinary_endpoint/ on or after March 15, 2020.