API Versioning

API Versioning Guidelines

Grants.gov is implementing and supporting versioning for all APIs to ensure stability and compatibility for our users.

1. Support for Versioning

All APIs include versioning to maintain clarity and avoid breaking existing integrations. The method for Grants.gov REST APIs is to include a major version number in the URL path, such as /v1/.

2. Major and Minor Versions

  • Major Versions (e.g., v1, v2):

    • Reserved for breaking changes and major updates that are incompatible with previous versions.

    • Example breaking changes include altering response formats or removing endpoints.

  • Minor Versions (e.g., 1.1, 2.3):

    • Optional but useful for indicating non-breaking updates or enhancements.

    • Minor versions should not be included in the URL. Instead, include them in HTTP headers (e.g., X-API-Version: 1.1).

3. Breaking Changes (Backwards Incompatible)

Breaking changes occur when updates disrupt the APIs and their users. To handle such scenarios:

  • Introduce a new major version to avoid disrupting existing users.

  • Communicate the changes and provide ample notice before deprecating older versions.

Examples of Breaking Changes for REST APIs:

  • Removing an HTTP method.

  • Renaming or removing fields in request/response messages.

  • Changing or removing query parameters.

  • Modifying the URL or its structure.

Examples of Breaking Changes:

  • Removing or renaming an operation.

  • Altering the parameters (data type or order) of an operation.

  • Restructuring a complex data type.

4. Non-Breaking Changes (Backwards Compatible)

Non-breaking updates enhance the API without affecting its existing behavior. For such changes:

  • Major version increment is not necessary.

  • Optionally reflect updates in the minor version, if applicable.

Examples of Non-Breaking Changes for REST APIs:

  • Adding new HTTP methods or endpoints.

  • Adding fields to request or response objects.

  • Introducing new query parameters or values.

Examples of Non-Breaking Changes for SOAP Web Services:

  • Adding new operations or XML schema types in the WSDL document.

  • Expanding existing structures without altering previous definitions.

5. Support for Previous Versions

  • Grants.gov will support at least one previous major version to ensure user adoption of newer versions is smooth.

  • Grants.gov will communicate deprecation timelines and guide users on transitioning to newer versions.