From 93fb1cc0bd1c28959632934a2426c2d420b173e3 Mon Sep 17 00:00:00 2001
From: aaa2000 <adev2000@gmail.com>
Date: Sun, 7 Dec 2025 17:33:26 +0100
Subject: [PATCH] Document Deprecation HTTP Header usage

Added guidance on setting the Deprecation HTTP header, including examples and usage of the deprecation header and deprecation link.
---
 core/deprecations.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/core/deprecations.md b/core/deprecations.md
index 08c9c2af756..313438a1885 100644
--- a/core/deprecations.md
+++ b/core/deprecations.md
@@ -169,6 +169,41 @@ class Parchment
 }
 ```
 
+### Setting the Deprecation HTTP Header to Indicate When an Operation Is Deprecated
+
+[The Deprecation HTTP Response Header Field (RFC 9745)](https://datatracker.ietf.org/doc/rfc9745/)
+indicates that a URI will be or has been deprecated. This header can be used alongside the `Sunset`
+header to provide a deprecation date and a link to relevant documentation. Additionally, the
+`deprecation` link relation can be used to point to a resource that provides further information
+about the planned or existing deprecation.
+
+To set a `Deprecation` header, use the `headers` option in the operation definition. The value of
+the `deprecation` header should be a Unix timestamp. You can also provide a `Link` header with a
+`deprecation` relation to give users more context about the deprecation:
+
+```php
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Link;
+
+#[ApiResource(
+    operations: [
+        new GetCollection(
+            headers: [
+                'deprecation' => '1688169599', // Unix timestamp
+            ],
+            links: [
+                new Link('deprecation', 'https://developer.example.com/deprecation'),
+            ],
+        ),
+    ],
+)]
+class DeprecationHeader
+{
+    // ...
+}
+```
+
 ## Path versioning
 
 > [!NOTE] REST and GraphQL architectures recommend to use deprecations instead of path versioning.