export const metadata = { title: ${pageNumber} API Route Parameters, }

{metadata.title}

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:

export const singlePathHighlights = [ ["11", "req.params.id", "Access the path parameter id."] ]

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

export const GET = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  res.json({
    message: `[GET] Hello ${req.params.id}!`,
  })
}

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:

export const multiplePathHighlights = [ ["12", "req.params.id", "Access the path parameter id."], ["13", "req.params.name", "Access the path parameter name."] ]

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

export const GET = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  res.json({
    message: `[GET] Hello ${
      req.params.id
    } - ${req.params.name}!`,
  })
}

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:

export const queryHighlights = [ ["11", "req.query.name", "Access the query parameter name."], ]

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

export const GET = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  res.json({
    message: `Hello ${req.query.name}`,
  })
}

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 the API Route Validation chapter.

Request Body Parameters

The Medusa application parses the body of any request with JSON, URL-encoded, or text content types. The request body parameters are set in the MedusaRequest's body property.

Learn more about configuring body parsing in the Body Parsing chapter.

For example:

export const bodyHighlights = [ ["11", "HelloWorldReq", "Specify the type of the request body parameters."], ["15", "req.body.name", "Access the request body parameter name."], ]

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

type HelloWorldReq = {
  name: string
}

export const POST = async (
  req: MedusaRequest<HelloWorldReq>,
  res: MedusaResponse
) => {
  res.json({
    message: `[POST] Hello ${req.body.name}!`,
  })
}

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

The MedusaRequest type accepts a type argument that indicates the type of the request body. This is useful for auto-completion and to avoid typing errors.

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

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

This returns the following JSON object:

{
  "message": "[POST] Hello John!"
}

Validate Body Parameters

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

Learn more in the Body Validation chapter.