From 1578e1ad22e6b0f0a5fed508bd7978310d584d53 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 3 Sep 2025 10:36:24 +0300 Subject: [PATCH] docs: add more examples for API route responses (#13399) --- .../api-routes/responses/page.mdx | 48 +++++++++++++++++-- www/apps/book/generated/edit-dates.mjs | 2 +- www/apps/book/public/llms-full.txt | 48 +++++++++++++++++-- 3 files changed, 91 insertions(+), 7 deletions(-) diff --git a/www/apps/book/app/learn/fundamentals/api-routes/responses/page.mdx b/www/apps/book/app/learn/fundamentals/api-routes/responses/page.mdx index 87f95b70e5..84323792a3 100644 --- a/www/apps/book/app/learn/fundamentals/api-routes/responses/page.mdx +++ b/www/apps/book/app/learn/fundamentals/api-routes/responses/page.mdx @@ -70,11 +70,53 @@ The response of this API route has the status code `201`. ## Change Response Content Type -To return response data other than a JSON object, use the `writeHead` method of the `MedusaResponse` object. It allows you to set the response headers, including the content type. +To return response data other than a JSON object, you can either use the `set`, `setHeader`, or `writeHead` methods of the `MedusaResponse` object. They allow you to set the response headers, including the content type. + +### Example: Return PDF File + +To create an API route that returns a PDF file, you can set the `Content-Type` header to `application/pdf`: + +```ts title="src/api/custom/route.ts" +import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" + +export const GET = async ( + req: MedusaRequest, + res: MedusaResponse +) => { + // assuming you have the PDF file as buffer + res.set({ + "Content-Type": "application/pdf", + "Content-Disposition": `attachment; filename="invoice-${id}.pdf"`, + "Content-Length": buffer.length, + }) + res.send(buffer) +} +``` + +The `set` method allows you to set multiple headers at once. It accepts an object of key-value header pairs. + +### Example: Return XML Content + +To create an API route that returns XML content, you can set the `Content-Type` header to `application/xml`: + +```ts title="src/api/custom/route.ts" +import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" + +export const GET = async ( + req: MedusaRequest, + res: MedusaResponse +) => { + // Assuming you have XML string + res.set({ + "Content-Type": "application/xml; charset=utf-8", + }) + res.send(xmlString) +} +``` ### Example: Server-Sent Events (SSE) -For example, to create an API route that returns server-sent events (SSE), you can set the `Content-Type` header to `text/event-stream`: +To create an API route that returns server-sent events (SSE), you can set the `Content-Type` header to `text/event-stream`: export const streamHighlights = [ ["7", "writeHead", "Set the response's headers."], @@ -121,7 +163,7 @@ The `writeHead` method accepts two parameters: This API route opens a stream by setting the `Content-Type` to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds. -### Tip: Fetching Stream with JS SDK +#### Tip: Fetching Stream with JS SDK The JS SDK has a `fetchStream` method that you can use to fetch data from an API route that returns a stream. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index 3a747779dd..e499550fe2 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -57,7 +57,7 @@ export const generatedEditDates = { "app/learn/debugging-and-testing/testing-tools/unit-tests/module-example/page.mdx": "2024-09-02T11:04:27.232Z", "app/learn/debugging-and-testing/testing-tools/unit-tests/page.mdx": "2024-09-02T11:03:26.997Z", "app/learn/fundamentals/modules/service-constraints/page.mdx": "2025-03-18T15:12:46.006Z", - "app/learn/fundamentals/api-routes/responses/page.mdx": "2025-08-01T14:15:34.787Z", + "app/learn/fundamentals/api-routes/responses/page.mdx": "2025-09-03T06:21:27.054Z", "app/learn/fundamentals/api-routes/validation/page.mdx": "2025-03-24T06:52:47.896Z", "app/learn/fundamentals/api-routes/errors/page.mdx": "2025-06-19T16:09:08.563Z", "app/learn/fundamentals/admin/constraints/page.mdx": "2025-07-21T08:20:43.223Z", diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index 14f4f62cff..12365514b4 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -9155,11 +9155,53 @@ The response of this API route has the status code `201`. ## Change Response Content Type -To return response data other than a JSON object, use the `writeHead` method of the `MedusaResponse` object. It allows you to set the response headers, including the content type. +To return response data other than a JSON object, you can either use the `set`, `setHeader`, or `writeHead` methods of the `MedusaResponse` object. They allow you to set the response headers, including the content type. + +### Example: Return PDF File + +To create an API route that returns a PDF file, you can set the `Content-Type` header to `application/pdf`: + +```ts title="src/api/custom/route.ts" +import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" + +export const GET = async ( + req: MedusaRequest, + res: MedusaResponse +) => { + // assuming you have the PDF file as buffer + res.set({ + "Content-Type": "application/pdf", + "Content-Disposition": `attachment; filename="invoice-${id}.pdf"`, + "Content-Length": buffer.length, + }) + res.send(buffer) +} +``` + +The `set` method allows you to set multiple headers at once. It accepts an object of key-value header pairs. + +### Example: Return XML Content + +To create an API route that returns XML content, you can set the `Content-Type` header to `application/xml`: + +```ts title="src/api/custom/route.ts" +import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" + +export const GET = async ( + req: MedusaRequest, + res: MedusaResponse +) => { + // Assuming you have XML string + res.set({ + "Content-Type": "application/xml; charset=utf-8", + }) + res.send(xmlString) +} +``` ### Example: Server-Sent Events (SSE) -For example, to create an API route that returns server-sent events (SSE), you can set the `Content-Type` header to `text/event-stream`: +To create an API route that returns server-sent events (SSE), you can set the `Content-Type` header to `text/event-stream`: ```ts highlights={streamHighlights} import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" @@ -9197,7 +9239,7 @@ The `writeHead` method accepts two parameters: This API route opens a stream by setting the `Content-Type` to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds. -### Tip: Fetching Stream with JS SDK +#### Tip: Fetching Stream with JS SDK The JS SDK has a `fetchStream` method that you can use to fetch data from an API route that returns a stream.