147 lines
3.9 KiB
Plaintext
147 lines
3.9 KiB
Plaintext
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 define a path parameter for an API route, create a directory as part of the route file’s path. The directory’s name is of the format `[param]`, where `param` is the name of the parameters.
|
||
|
||
For example, to create an API Route at the path `/message/{id}`, where `{id}` is an ID that can be passed to the route, create the file `src/api/store/hello-world/[id]/route.ts` with the following content:
|
||
|
||
export const singlePathHighlights = [
|
||
["11", "req.params.id", "Access the path parameter `id`"]
|
||
]
|
||
|
||
```ts title="src/api/store/hello-world/[id]/route.ts" highlights={singlePathHighlights}
|
||
import type {
|
||
MedusaRequest,
|
||
MedusaResponse,
|
||
} from "@medusajs/medusa"
|
||
|
||
export const GET = (
|
||
req: MedusaRequest,
|
||
res: MedusaResponse
|
||
) => {
|
||
res.json({
|
||
message: `[GET] Hello ${req.params.id}!`,
|
||
})
|
||
}
|
||
```
|
||
|
||
You can access the path parameter using the `params` property of the `MedusaRequest` parameter. The `params` property is an object whose keys are the parameter names, and the values are each parameter’s value passed in the route’s path.
|
||
|
||
### Multiple Path Parameters
|
||
|
||
Each directory in the route file’s path whose name is of the format `[param]` is considered a path parameter. However, every parameter name must be unique.
|
||
|
||
For example, you can create an API route at `src/api/store/hello-world/[id]/name/[name]/route.ts`:
|
||
|
||
export const multiplePathHighlights = [
|
||
["11", "req.params.id", "Access the path parameter `id`"],
|
||
["11", "req.params.name", "Access the path parameter `name`"]
|
||
]
|
||
|
||
```ts title="src/api/store/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights}
|
||
import type {
|
||
MedusaRequest,
|
||
MedusaResponse,
|
||
} from "@medusajs/medusa"
|
||
|
||
export const GET = (
|
||
req: MedusaRequest,
|
||
res: MedusaResponse
|
||
) => {
|
||
res.json({
|
||
message: `[GET] Hello ${req.params.id} - ${req.params.name}!`,
|
||
})
|
||
}
|
||
```
|
||
|
||
This API route expects two path parameters: `id` and `name`.
|
||
|
||
---
|
||
|
||
## Query Parameters
|
||
|
||
You can access all query parameters in the `query` property of the `MedusaRequest` parameter.
|
||
|
||
For example:
|
||
|
||
export const queryHighlights = [
|
||
["11", "req.query.name", "Access the query parameter `name`"],
|
||
]
|
||
|
||
```ts title="src/api/store/hello-world/route.ts" highlights={queryHighlights}
|
||
import type {
|
||
MedusaRequest,
|
||
MedusaResponse,
|
||
} from "@medusajs/medusa"
|
||
|
||
export async function GET(
|
||
req: MedusaRequest,
|
||
res: MedusaResponse
|
||
): Promise<void> {
|
||
res.json({
|
||
message: `Hello ${req.query.name}`,
|
||
})
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Request Body Parameters
|
||
|
||
By default, any request sent to your Medusa application with its `Content-Type` header set to `application/json` is parsed into an object and attached to the `MedusaRequest`'s `body` property.
|
||
|
||
For example:
|
||
|
||
export const bodyHighlights = [
|
||
["15", "req.body.name", "Access the request body parameter `name`"],
|
||
]
|
||
|
||
```ts title="src/api/store/hello-world/route.ts" highlights={bodyHighlights}
|
||
import type {
|
||
MedusaRequest,
|
||
MedusaResponse,
|
||
} from "@medusajs/medusa"
|
||
|
||
type HelloWorldReq = {
|
||
name: string
|
||
}
|
||
|
||
export const POST = (
|
||
req: MedusaRequest<HelloWorldReq>,
|
||
res: MedusaResponse
|
||
) => {
|
||
res.json({
|
||
message: `[POST] Hello ${req.body.name}!`,
|
||
})
|
||
}
|
||
```
|
||
|
||
The `MedusaRequest` type accepts a type argument indicating the expected request body parameters.
|
||
|
||
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:
|
||
|
||
```bash apiTesting testApiUrl="http://localhost:9000/store/hello-world" testApiMethod="POST" testBodyParams={{ "name": "John" }}
|
||
curl -X POST http://localhost:9000/store/hello-world \
|
||
--header 'Content-Type: application/json' \
|
||
--data-raw '{
|
||
"name": "John"
|
||
}'
|
||
```
|
||
|
||
This returns the following JSON object:
|
||
|
||
```json
|
||
{
|
||
"message": "[POST] Hello John!"
|
||
}
|
||
```
|