API Versioning

USGS water data APIs are hosted at https://api.waterdata.usgs.gov/ogcapi/v0/. The "v0" at the end of the URL indicates the version of the APIs that you're accessing. Currently only v0 is available.

We refer to the current version of the APIs as "v0" because we're still developing the core endpoints and features that we want these APIs to provide. Once these are available, we intend to advance to the "v1" of these APIs, with a new URL to match. Both the v0 and v1 of the APIs will run concurrently for a period to allow you to gradually migrate your workflows to the new services once they exist.

We aim to not release any breaking changes within a single version of an API. This means that any query which currently succeeds against the v0 of the APIs should continue to succeed against v0, though you might need to make some updates when we release v1. It doesn't mean that we won't make changes to the API's interface or that the underlying data a query searches for won't change.

A breaking change is something that causes a query which previously succeeded to start failing. Examples of breaking changes include:

• Renaming endpoints,
• Removing fields from an endpoint's response,
• Renaming fields in an endpoint's response,
• Removing output formats from an endpoint,
• Changing the default return format for an endpoint.
• Changing structures of response formats (for instance, moving a field from a nested JSON array into the top-level "properties" array), and
• Changing data types of a field (for instance, converting a numeric field to a string).

Each of these changes have the potential to cause existing queries to fail. As such, we will endeavour to avoid making any of these changes within a single version of the APIs.

Not all significant changes will cause query failure, however, and as such can be implemented within a single API version. Examples of non-breaking changes include:

• Adding new endpoints,
• Adding fields to an endpoint's response,
• Introducing additional output formats,
• Adding query parameters to an endpoint,
• Changing the default values of non-filtering query parameters (for instance, limit),
• Changing the internal logic of the APIs (for instance, changing how next links are generated),
• Changes to the data provided by the APIs (due to revisions or other updates).

Note that we also do not guarantee the order that results are returned in, or the order that fields are sorted in within a response object.

To the greatest extent possible we will release non-breaking changes within a version to help users anticipate breaking changes that might occur across versions. For instance, user feedback has indicated that the "begin" and "end" fields available from the /time-series-metadata endpoint would be more useful if they were in UTC and contained time zone information. In this situation, we may add fields to the v0 /time-series-metadata endpoint implementing this change (for example, "begin_utc" and "end_utc") while maintaining the existing "begin" and "end" fields, while the v1 field may redefine the data provided by "begin" and "end" fields instead.

When a new version is released, it will operate concurrently with the older version for a period of time to allow you to migrate over. We will not maintain older versions of the API indefinitely. New version releases and decommission dates for older versions will both be announced on the WDFN blog and through the WDFN newsletter.