Aggresive Obsolescence

_{Published: 22 April 2025}

Known Uses

This pattern is not widely adopted in the energy sector. However, a few examples exist in the Dutch government sector:

• In the Kadaster BAG API Individual Queries (Basic Registration of Addresses and Buildings), the OpenAPI specification uses deprecated: true to indicate that the Accept-Crs header is deprecated, as well as the GET /adressen/zoek operation
• Allmanak: Directory Search for contact details of governments and politicians uses a well-defined deprecation policy

Discussion Input

This pattern is primarily aimed at decommissioning entire APIs or outdated components, such as operations or message elements. The Sunset and Deprecation HTTP headers are specifically designed to indicate the planned decommissioning of a resource, method, or endpoint — but not for individual fields within a request or response body. These headers operate at the HTTP resource level, not at the payload or schema level.

When it comes to deprecating a field within a payload, several approaches are possible:

• Announce it via changelogs and API documentation.
• Mark it as deprecated in the OpenAPI (OAS) specification.
• Remove it in the next API version (e.g., deprecated in v1, removed in v2).
• Optionally use the HTTP Warning header (code 299) to surface a notice alongside the response if you want to highlight it at runtime.

It’s worth noting that the use of the Deprecation header is currently a topic of discussion in the Dutch government sector, as the IETF has just published RFC 9745, which formally defines The Deprecation HTTP Response Header Field.

Recommended Reading

• API Deprecation and Sunset — Erik Wilde (LinkedIn)