Learn how hints can be transmitted to clients via the optional but useful Sunset and Deprecation HTTP Headers.

1. Introduction

According to Richardson Maturity Model [Reference 1], a Level 3 REST architecture introduces discoverability through hypermedia controls in addition to resources and HTTP verbs, thus making communication between the involved actors more self-documenting.

Hypermedia enriches the interaction from various perspectives, decreasing the coupling between parties and also allowing them to evolve independently. Moreover, the data enclosed in the exchanged messages is enhanced with links, which makes the overall exchanged information more accurate. On the other hand, developers now need to pay more attention when thinking the design, as the representations have a greater impact.

HATEOAS (Hypermedia as the Engine of the Application State) is an architectural component that allows driving application state (resources’ representations) enhanced with hypermedia support.

Currently, the most common REST API implementations are those conforming to Level 2 (Reference 1), which (most of the time) fully solve the required business problems and thus are enough. A Level 3, on the other hand, provides more insights, as previously stated. Moreover, a REST API service provider can make a better promise (Reference 2) to its customers if for certain business use cases additional pieces of information (hints) are provided. If leveraged, these might make the contract between the two go even smoother.

This post describes how such hints can be transmitted to clients via the optional but useful Sunset and Deprecation HTTP Headers.

#tutorial #api #spring #rest #hateoas #respectful rest apis: ‘sunset’ and ‘deprecation’ http headers