API Route Parameters

In this chapter, you’ll learn about path, query, and request body parameters.

Path Parameters#

To create an API route that accepts a path parameter, create a directory within the route file's path whose name is of the format [param].

For example, to create an API Route at the path /hello-world/:id, where :id is a path parameter, create the file src/api/hello-world/[id]/route.ts with the following content:

src/api/hello-world/[id]/route.ts
1import type {2  MedusaRequest,3  MedusaResponse,4} from "@medusajs/framework/http"5
6export const GET = async (7  req: MedusaRequest,8  res: MedusaResponse9) => {10  res.json({11    message: `[GET] Hello ${req.params.id}!`,12  })13}

The MedusaRequest object has a params property. params holds the path parameters in key-value pairs.

Multiple Path Parameters#

To create an API route that accepts multiple path parameters, create within the file's path multiple directories whose names are of the format [param].

For example, to create an API route at /hello-world/:id/name/:name, create the file src/api/hello-world/[id]/name/[name]/route.ts with the following content:

src/api/hello-world/[id]/name/[name]/route.ts
1import type {2  MedusaRequest,3  MedusaResponse,4} from "@medusajs/framework/http"5
6export const GET = async (7  req: MedusaRequest,8  res: MedusaResponse9) => {10  res.json({11    message: `[GET] Hello ${12      req.params.id13    } - ${req.params.name}!`,14  })15}

You access the id and name path parameters using the req.params property.

Query Parameters#

You can access all query parameters in the query property of the MedusaRequest object. query is an object of key-value pairs, where the key is a query parameter's name, and the value is its value.

For example:

src/api/hello-world/route.ts
1import type {2  MedusaRequest,3  MedusaResponse,4} from "@medusajs/framework/http"5
6export const GET = async (7  req: MedusaRequest,8  res: MedusaResponse9) => {10  res.json({11    message: `Hello ${req.query.name}`,12  })13}

The value of req.query.name is the value passed in ?name=John, for example.

Validate Query Parameters#

You can apply validation rules on received query parameters to ensure they match specified rules and types.

Learn more in this documentation.

Request Body Parameters#

The Medusa application parses the body of any request having its Content-Type header set to application/json. The request body parameters are set in the MedusaRequest's body property.

For example:

src/api/hello-world/route.ts
1import type {2  MedusaRequest,3  MedusaResponse,4} from "@medusajs/framework/http"5
6type HelloWorldReq = {7  name: string8}9
10export const POST = async (11  req: MedusaRequest<HelloWorldReq>,12  res: MedusaResponse13) => {14  res.json({15    message: `[POST] Hello ${req.body.name}!`,16  })17}

In this example, you use the name request body parameter to create the message in the returned response.

To test it out, send the following request to your Medusa application:

Code
1curl -X POST 'http://localhost:9000/hello-world' \2-H 'Content-Type: application/json' \3--data-raw '{4  "name": "John"5}'

This returns the following JSON object:

Code
1{2  "message": "[POST] Hello John!"3}

Validate Body Parameters#

You can apply validation rules on received body parameters to ensure they match specified rules and types.

Learn more in this documentation.