Deprecation Headers — SunSetting Old API Versions

In this tutorial, you will learn about Deprecation Headers. We cover key concepts, practical examples, and best practices to help you master this topic.

Deprecation headers provide real-time communication to API clients about deprecated versions, sunset timelines, and successor versions through standard HTTP headers.

Header Specifications

Deprecation: true indicates the version is deprecated. Sunset: HTTP-date specifies when the version will be removed. Link: rel="successor-version" points to replacement.

Implementation

app.get("/api/v1/users", (req, res) => {
  res.set("Deprecation", "true");
  res.set("Sunset", "Sat, 31 Dec 2026 23:59:59 GMT");
  res.set("Link", '</api/v2/users>; rel="successor-version"');
  res.json(usersV1);
});

Common Mistakes

1. No deprecation headers — Removing versions without warning clients.
2. Missing sunset date — Deprecated but never removed.
3. No successor link — Clients do not know what to migrate to.

Practice Questions

1. What does the Deprecation header indicate?
2. What does the Sunset header specify?
3. How do you indicate the replacement version?

Challenge

Implement deprecation headers for v1 of an API. Log usage of deprecated versions for analytics. Set sunset date 6 months in the future.

What's Next

In the next lesson, you will learn Migration guides.