dos: add docs on overriding allowed fields in routes (#12233)

www/apps/book/app/learn/customization/extend-features/query-linked-records/page.mdx

@@ -31,7 +31,7 @@ Medusa's existing API routes accept a `fields` query parameter that allows you t
 
 <Note>
 
-Learn more about selecting fields and relations in the [API Reference](!api!/admin#select-fields-and-relations).
+Learn more about using the `fields` query parameter to retrieve custom linked data models in the [Retrieve Custom Linked Data Models from Medusa's API Routes](../../../fundamentals/api-routes/retrieve-custom-links/page.mdx) chapter.
 
 </Note>
 

www/apps/book/app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx

@@ -0,0 +1,92 @@
+export const metadata = {
+  title: `${pageNumber} Retrieve Custom Links from Medusa's API Route`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn how to retrieve custom data models linked to existing Medusa data models from Medusa's API routes.
+
+## Why Retrieve Custom Linked Data Models?
+
+Often, you'll link custom data models to existing Medusa data models to implement custom features or expand on existing ones.
+
+For example, to add brands for products, you can create a `Brand` data model in a Brand Module, then [define a link](../../module-links/page.mdx) to the [Product Module](!resources!/commerce-modules/product)'s `Product` data model.
+
+When you implement this customization, you might need to retrieve the brand of a product using the existing [Get Product API Route](!api!/admin#products_getproductsid). You can do this by passing the linked data model's name in the `fields` query parameter of the API route.
+
+---
+
+## How to Retrieve Custom Linked Data Models Using `fields`?
+
+Most of Medusa's API routes accept a `fields` query parameter that allows you to specify the fields and relations to retrieve in the resource, such as a product.
+
+For example, to retrieve the brand of a product, you can pass the `brand` field in the `fields` query parameter of the [Get Product API Route](!api!/admin#products_getproductsid):
+
+```bash
+curl 'http://localhost:9000/admin/products/{id}?fields=*brand' \
+-H 'Authorization: Bearer {access_token}'
+```
+
+The `fields` query parameter accepts a comma-separated list of fields and relations to retrieve. To learn more about using the `fields` query parameter, refer to the [API Reference](!api!/store#select-fields-and-relations).
+
+By prefixing `brand` with an asterisk (`*`), you retrieve all the default fields of the product, including the `brand` field. If you don't include the `*` prefix, the response will only include the product's brand.
+
+---
+
+## API Routes that Restrict Retrievable Fields
+
+Some of Medusa's API routes restrict the fields and relations you can retrieve, which means you can't pass your custom linked data models in the `fields` query parameter. Medusa makes this restriction to ensure the API routes are performant and secure.
+
+The API routes that restrict the fields and relations you can retrieve are:
+
+- [Customer Store API Routes](!api!/store#customers)
+- [Customer Admin API Routes](!api!/admin#customers)
+- [Product Category Admin API Routes](!api!/admin#product-categories)
+
+### How to Override Allowed Fields and Relations
+
+For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by adding a [middleware](../middlewares/page.mdx) to those routes.
+
+For example, to allow retrieving the `b2b_company` of a customer using the [Get Customer Admin API Route](!api!/admin#customers_getcustomersid), create the file `src/api/middlewares.ts` with the following content:
+
+<Note>
+
+Learn how to create a middleware in the [Middlewares](../middlewares/page.mdx) chapter.
+
+</Note>
+
+export const highlights = [
+  ["10", "req.allowed", "Modify the allowed fields and relations to be retrieved"],
+]
+
+```ts title="src/api/middlewares.ts" highlights={highlights}
+import { defineMiddlewares } from "@medusajs/medusa";
+
+export default defineMiddlewares({
+  routes: [
+    {
+      matcher: "/store/customers/me",
+      method: "GET",
+      middlewares: [
+        (req, res, next) => {
+          req.allowed?.push("b2b_company");
+          next();
+        },
+      ],
+    },
+  ],
+});
+```
+
+In this example, you apply a middleware to the [Get Customer Admin API Route](!api!/admin#customers_getcustomersid).
+
+The request object passed to middlewares has an `allowed` property that contains the fields and relations that can be retrieved. So, you modify the `allowed` array to include the `b2b_company` field.
+
+You can now retrieve the `b2b_company` field using the `fields` query parameter of the [Get Customer Admin API Route](!api!/admin#customers_getcustomersid):
+
+```bash
+curl 'http://localhost:9000/admin/customers/{id}?fields=*b2b_company' \
+-H 'Authorization: Bearer {access_token}'
+```
+
+In this example, you retrieve the `b2b_company` relation of the customer using the `fields` query parameter.

www/apps/book/generated/edit-dates.mjs

@@ -85,7 +85,7 @@ export const generatedEditDates = {
   "app/learn/customization/customize-admin/widget/page.mdx": "2025-02-05T09:10:18.163Z",
   "app/learn/customization/extend-features/define-link/page.mdx": "2025-04-17T08:50:17.036Z",
   "app/learn/customization/extend-features/page.mdx": "2024-12-09T11:02:39.244Z",
-  "app/learn/customization/extend-features/query-linked-records/page.mdx": "2025-03-25T13:48:49.973Z",
+  "app/learn/customization/extend-features/query-linked-records/page.mdx": "2025-04-18T07:41:05.912Z",
   "app/learn/customization/integrate-systems/handle-event/page.mdx": "2024-12-24T15:09:24.653Z",
   "app/learn/customization/integrate-systems/page.mdx": "2024-12-09T10:40:08.528Z",
   "app/learn/customization/integrate-systems/schedule-task/page.mdx": "2025-01-28T16:42:42.071Z",
@@ -119,5 +119,6 @@ export const generatedEditDates = {
   "app/learn/production/worker-mode/page.mdx": "2025-03-11T15:21:50.906Z",
   "app/learn/fundamentals/module-links/read-only/page.mdx": "2025-03-21T09:14:54.944Z",
   "app/learn/fundamentals/data-models/properties/page.mdx": "2025-03-18T07:57:17.826Z",
-  "app/learn/fundamentals/framework/page.mdx": "2025-04-17T16:07:19.090Z"
+  "app/learn/fundamentals/framework/page.mdx": "2025-04-17T16:07:19.090Z",
+  "app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx": "2025-04-18T07:38:56.729Z"
 }

www/apps/book/generated/sidebar.mjs

@@ -628,10 +628,20 @@ export const generatedSidebars = [
                 "isPathHref": true,
                 "type": "link",
                 "path": "/learn/fundamentals/api-routes/additional-data",
-                "title": "Additional Data",
+                "title": "Pass Additional Data",
                 "children": [],
-                "chapterTitle": "3.6.10. Additional Data",
+                "chapterTitle": "3.6.10. Pass Additional Data",
                 "number": "3.6.10."
+              },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "path": "/learn/fundamentals/api-routes/retrieve-custom-links",
+                "title": "Retrieve Custom Links",
+                "children": [],
+                "chapterTitle": "3.6.11. Retrieve Custom Links",
+                "number": "3.6.11."
               }
             ],
             "chapterTitle": "3.6. API Routes",

www/apps/book/sidebar.mjs

@@ -332,7 +332,12 @@ export const sidebars = [
               {
                 type: "link",
                 path: "/learn/fundamentals/api-routes/additional-data",
-                title: "Additional Data",
+                title: "Pass Additional Data",
+              },
+              {
+                type: "link",
+                path: "/learn/fundamentals/api-routes/retrieve-custom-links",
+                title: "Retrieve Custom Links",
               },
             ],
           },