Add details and examples in new response format page

Author: Mégane Lacheny

docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/new-response-format.md

@@ -98,7 +98,48 @@ The Content API returns attributes of requested content without wrapping them in
 
 ### Notes
 
-To use the Strapi v4 response format, set the following header: `Strapi-Response-Format: v4`. 
+The `Strapi-Response-Format: v4` header temporarily restores the Strapi v4 wrapping (`data.attributes.*`). You can keep the header in place while you update each consumer, then remove it once every client can read the flattened format. The header affects REST calls, including population on relations, but does not roll back the introduction of [`documentId`](/cms/migration/v4-to-v5/breaking-changes/use-document-id).
+
+To use the compatibility header while migrating:
+
+1. Capture a few baseline responses before you switch the header on. These samples help you compare payloads once `attributes` comes back and ensure that relations, components, and nested populations all respond as expected.
+2. Add the `Strapi-Response-Format: v4` header to every REST request made by legacy clients. Remove it only after you have updated and tested each endpoint.
+3. Keep in mind that `documentId` continues to be the only identifier returned by the REST API when the header is absent. With the header enabled, REST responses include both `id` (for backward compatibility) and `documentId` (the canonical identifier). Plan to migrate any downstream systems that still depend on numeric `id`.
+
+<details>
+<summary>Examples</summary>
+```bash title="curl"
+curl \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Strapi-Response-Format: v4' \
+  'https://api.example.com/api/articles?populate=category'
+```
+
+```js title="fetch"
+await fetch('https://api.example.com/api/articles', {
+  headers: {
+    Authorization: `Bearer ${token}`,
+    'Strapi-Response-Format': 'v4',
+  },
+});
+```
+
+```js title="Axios"
+const client = axios.create({
+  baseURL: 'https://api.example.com/api',
+  headers: {
+    Authorization: `Bearer ${token}`,
+    'Strapi-Response-Format': 'v4',
+  },
+});
+
+const articles = await client.get('/articles', { params: { populate: '*'} });
+```
+</details>
+
+:::tip
+If you need to keep a mix of formats running, enable the header for any routes that still rely on `attributes`, then gradually remove it per endpoint or per consumer once you finish testing.
+:::
 
 ### Manual procedure
 

docusaurus/static/llms-full.txt

@@ -9244,6 +9244,18 @@ Strapi Cloud will deploy the updated code in Strapi 5 and will automatically run
 
 </details>
 
+<details style={{backgroundColor: 'transparent', border: 'solid 1px #4945ff' }}>
+<summary style={{fontSize: '18px'}}>How do I keep the legacy <code>attributes</code> wrapper during the migration?</summary>
+
+- For REST clients, add the `Strapi-Response-Format: v4` header while you refactor your code. The [new response format breaking change](/cms/migration/v4-to-v5/breaking-changes/new-response-format#use-the-compatibility-header-while-migrating) shows where to add the header in `curl`, `fetch`, and Axios requests.
+- For GraphQL clients, enable `v4CompatibilityMode` and follow the steps of the [GraphQL API migration documentation](/cms/migration/v4-to-v5/breaking-changes/graphql-api-updated#migration) to gradually remove `attributes`.
+- REST responses continue to expose both `id` (legacy) and [`documentId`](/cms/migration/v4-to-v5/breaking-changes/use-document-id) when the header is enabled. GraphQL never exposes numeric `id`, so update your queries to use `documentId` even before you turn compatibility mode off.
+
+Once every consumer reads the flattened format, remove the header so Strapi emits the Strapi 5 response shape by default.
+<br/>
+
+</details>
+
 
 
 # Step-by-step guide to upgrade to Strapi 5
@@ -9338,7 +9350,7 @@ For each of them, read the indicated breaking change entry and check if some man
 
 Strapi 5 has updated both the REST and GraphQL APIs.
 
-Follow the steps below and leverage retro-compatibility flags and guided migration resources to gradually update your code for Strapi 5.
+Follow the steps below and leverage retro-compatibility headers and guided migration resources to gradually update your code for Strapi 5.
 
 ### Migrate REST API calls
 
@@ -9355,7 +9367,7 @@ Follow the steps below and leverage retro-compatibility flags and guided migrati
 1. Enable the compatibility header by setting `v4CompatibilityMode` to `true` in the `graphql` plugin configuration, so clients can continue to rely on `data.attributes` while you refactor them.
 2. Follow each step of the [breaking change entry for GraphQL](/cms/migration/v4-to-v5/breaking-changes/graphql-api-updated). This will guide you to swap `id` for `documentId`, adopt `_connection` queries, remove `attributes`, and finally switch to `nodes/pageInfo`.
 3. Test Relay and non-Relay queries by confirming that pagination metadata still matches expectations when you remove `_connection` and `data` for clients that do not need Relay semantics.
-4. Disable the `v4CompatibilityMode` compatibility header: after every query and mutation works with the flattened schema, set the flag to `false` so the server emits the Strapi 5 format by default.
+4. Disable the `v4CompatibilityMode` compatibility header: after every query and mutation works with the flattened schema, set the header to `false` so the server emits the Strapi 5 format by default.