Deprecating APIs – kill switches and dead man's switches

Sunset

With RFC 9745 (Deprecation Header) and RFC 8594 (Sunset Header), the Internet Engineering Task Force (IETF) offers clear mechanisms for communicating the end of an HTTP API endpoint. Client developers can thus automatically recognise when resources become obsolete and when they are shut down. These two standards support proactive maintenance and facilitate migration to new interfaces.

The Deprecation Header specifies the date from which an endpoint is considered obsolete. This date can be in the future or in the past. The Sunset header defines the point in time at which an API endpoint is no longer accessible and its behaviour becomes undefined. If both headers are used simultaneously, the Sunset date should be after the Deprecation date.

These two HTTP headers can be used to communicate a clear schedule for the transition phase to API users at a technical level.

In the example shown in Figure 1, the API will be marked as deprecated on 1 January 2026. After the sunset date of 31 December 2026, the behaviour of the resource will no longer be defined.

In addition to the deprecation and sunset headers, links (RFC 8288) can also be sent in the header. These link headers should contain a URL to a document that describes the background of the deprecation in a human-readable format.

The API documentation must indicate that the information described in the header can be sent along with the request. In the OpenAPI documentation, for example, the header information is marked as optional. Users of the API can then design their system in such a way that the information is evaluated and they are informed when the deprecation occurs.

Use case in bounded context

We have not yet applied the mechanism described in our project. Our bounded context acts more as a customer of other APIs and does not provide any public APIs itself. This changed when the boundary of our bounded context had to be shifted as part of an emergency solution.

A bounded context defines technical and linguistic boundaries within a domain in order to organise larger systems into specific sub-areas. It is usually the responsibility of a team. The clear delineation of responsibilities in a bounded context is essential for stable and strategically clean software design and is part of domain-driven design (DDD).

Our bounded context can be defined as follows: Management of customer access to the client's direct communication channel by the customer's administrative staff.

In concrete terms, this means that our team decides whether a customer can participate in the client's direct communication channel.

The domain of our bounded context is located in a regulated environment. Within this domain, there is another bounded context that provides the communication channel. This channel must be able to establish a connection between a customer and an employee. This was underestimated during project planning.

To establish the connection, a request must be sent to the customer's enterprise resource planning (ERP) system. Since the communication channel team cannot meet the current schedule, it was decided that our team would provide an interface to establish the connection. A new HTTP endpoint receives a request from the communication channel and forwards it to the ERP. This keeps the workload for the communication channel team manageable. On our side, however, it is considerably more complicated, as we also have to implement extensive additions to the ERP system.

This change shifts the boundary of our bounded context. It now regulates not only customer access to the client's direct communication channel, but also employee access to customers. This reverses the original boundary. In addition, the workaround creates a cyclical dependency between the two bounded contexts.

In such cases, it is often argued that such a small adjustment is not a problem. However, such an argument must be countered immediately. This is because such tactical emergency solutions poison the strategic design. And every small poisoning of a bounded context leads to greater poisoning. Once the door has been opened, it will not remain a small poisoning.

Everyone in both teams is unhappy with the chosen emergency solution. It was therefore decided that the communication channel team would take on the proxy task, provided that there was sufficient capacity available. However, our product owner, who has many years of experience with the organisation, suspects that this capacity will never be available.

The measure

We therefore need to get the communication channel team to start replacing the emergency solution as soon as possible. Together with the product owner, we have developed a multi-stage concept for this.

In a first step, a change request ticket was created in the communication channel team's backlog. This simply states that the previous route via the proxy should be dismantled as soon as possible. In the second step, the deprecation and sunset header entries were announced in the proxy's OpenAPI documentation. Both documentation measures involved very little effort. These simple measures gave the product owner the opportunity to announce the shutdown technically, in addition to verbal and written communication about the discontinuation of the emergency solution. Activating the discontinuation can also be implemented with little effort.

On the other hand, the team should implement a reverse dead man's switch for the communication channels. This can be done iteratively after the actual implementation of proxy communication. This involves regularly checking whether deprecation and sunset headers are set for the API. The team can be notified, for example, by an alarm in the monitoring system. The team then has the opportunity to take appropriate action.

Conclusion

As architects, we have found a socio-technical solution to give our product owner technical and political design options for protecting his bounded context. I cannot tell you at this point whether he will implement this, as he always has the final say on both the activation and the concrete deactivation of the emergency solution.