Deprecations
We keep the public API focused so we can maintain backward compatibility and avoid deprecations whenever possible. When an endpoint or field needs to change, we normally give you at least 30 days to migrate. It stays functional until the announced timestamp. After that deadline, it may stop working, or an older version may receive an inert placeholder that still satisfies the field's type.
The API announces the deadline in response headers so your integration can alert you automatically. If we must make a change with less than 30 days' notice, we email everyone who has created an API key.
Deprecation headers
When a request calls a deprecated endpoint, sends a deprecated field, or gets one back in the response, the response includes two headers:
| Header | Value |
|---|---|
deprecation | The earliest deprecation date involved, as @ followed by Unix seconds. Defined in RFC 9745. |
x-deprecated | Each deprecated endpoint or field the request touched, in quotes, with its own date. |
HTTP/1.1 200 OK
deprecation: @1795046400
x-deprecated: "<deprecated endpoint>";date=@1795046400, "<deprecated field>";date=@1796256000The angle-bracketed names above are illustrative placeholders, not actual deprecations.
- An endpoint is named by its method and path, as in the API reference. A field is named by its key. Deprecated fields and parameters have
deprecated: truein the OpenAPI document at/openapi.json. - A future date is your migration deadline. Before it, the endpoint or field remains functional. A past date means the deadline has passed; do not rely on the field still containing useful data.
- Error responses carry the headers too, not just successful ones.
- We send the headers until 30 days after each deprecation date. After that, the endpoint or field may still work, but the API stops warning you, so alert as soon as the headers appear.
Get alerted
Check every response for x-deprecated, and log a warning with the request that triggered it and the names it lists. Send those warnings to whatever already pages or notifies your team, such as your logging or error-tracking service, and alert on them.
async function fetchWithDeprecationWarnings(
request: Request,
): Promise<Response> {
const response = await fetch(request)
const deprecated = response.headers.get("x-deprecated")
if (deprecated !== null) {
const { pathname } = new URL(request.url)
console.warn(
`GovDash deprecation in ${request.method} ${pathname}: ${deprecated}`,
)
}
return response
}import logging
import os
import requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['GOVDASH_API_KEY']}"
session.headers["govdash-version"] = os.environ["GOVDASH_API_VERSION"]
def warn_on_deprecation(response, *args, **kwargs):
deprecated = response.headers.get("x-deprecated")
if deprecated is not None:
logging.warning(
"GovDash deprecation in %s %s: %s",
response.request.method,
response.request.path_url,
deprecated,
)
session.hooks["response"].append(warn_on_deprecation)Some HTTP clients and API gateways already understand the standard deprecation header and can report it for you. x-deprecated tells you what to change.