146 lines
3.7 KiB
Plaintext
146 lines
3.7 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 create an API route that accepts a path parameter, create a directory within the route's path whose name is of the format `[param]`.
|
||
|
||
For example, to create an API Route at the path `/message/{id}`, where `{id}` is a path parameter, 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}!`,
|
||
})
|
||
}
|
||
```
|
||
|
||
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, 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` object.
|
||
|
||
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
|
||
|
||
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:
|
||
|
||
export const bodyHighlights = [
|
||
["11", "HelloWorldReq", "Specify the type of the request body parameters."],
|
||
["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}!`,
|
||
})
|
||
}
|
||
```
|
||
|
||
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' \
|
||
-H 'Content-Type: application/json' \
|
||
--data-raw '{
|
||
"name": "John"
|
||
}'
|
||
```
|
||
|
||
This returns the following JSON object:
|
||
|
||
```json
|
||
{
|
||
"message": "[POST] Hello John!"
|
||
}
|
||
```
|