API Versions

Documentation > IPUMS API Program > API Versioning

IPUMS API Versions and Versioning Strategy

Currently Supported IPUMS API Versions

  • Version 2. Released March 6, 2023. Current version.
  • Version 1. Released March 6, 2023. Will be maintained until at least March 6, 2024.

See the Changelog for details.

The Unified IPUMS API Versioning Strategy

In 2023 we unified all external IPUMS API functionality under the singular “IPUMS API” moniker. This will allow us to more easily communicate with our users about the API.

To initially implement this change, in March 2023 we released Version 1 of the IPUMS API. Version 1 consolidated all functionality that had been released to date.

We concurrently released Version 2, which contained a number of previously unreleased features and an additional data collection, as well as a breaking change to previously released functionality.

Future IPUMS API Versioning

Moving forward, we will manage IPUMS API versions based on whether or not we are introducing breaking changes. A breaking change is a change that could cause an error with existing software which consumes our API.

Breaking Changes will Result in a New Version

If changes that we introduce would break existing clients of the API, we will release those changes as a new API version.

Breaking changes include:

  • Removal of an endpoint, endpoint parameter, response field, or valid value for a parameter or field
  • Addition of a required parameter without a default value
  • Changing the data type of a parameter or field
  • Introduction of a new validation which could render a previously-valid payload invalid

Since all API calls require a version to be specified in the URL, existing software would not be exposed to the breaking changes inadvertently.

Non-Breaking Changes will Extend the Current Version

If changes are non-breaking, we will introduce them into the current version.

Non-breaking changes include:

  • New endpoints or new methods on an existing endpoint
  • New response payload fields
  • New optional request payload fields
  • New optional parameters
  • New valid values for a field or parameter
  • New required request fields with default values
  • Changes to error messages
  • Bugfixes that don’t change intended functionality but correct previously incorrect behavior

Announcing and Identifying Changes

All changes will be announced on the Changelog / What’s New page and on our documentation site’s front page news feed. Significant changes may also be announced via our mailing lists or the IPUMS Forum.

Identifying Non-Breaking Changes

Non-breaking changes do not result in a new API version. However we will announce releases of non-breaking changes into an existing version as timestamped “changesets” in our Changelog, for example the “March 2023 Changeset”. This will allow us and third parties to unambiguously communicate when new features or data collections were/will be added or to indicate the current level of support in API client SDK tools. Hypothetical examples: “IPUMS International’s API functionality will become feature-complete with the webapp as of IPUMS API Version 3’s October 2024 changeset” or “the ipumspy IPUMS Python SDK supports IPUMS API Version 2 through the March 2023 changeset.”

Maintaining Older Versions

Versions will be maintained for at least one year after the release of the next version to allow time for migration of tools to the current API version. New functionality other than bugfixes will only be added to the latest version. Bugfixes will be added to all currently maintained versions that are affected by the bug.