1d54e8fdc1
- Add new documentation pages for API route intro, responses, errors, and validation - General fixes and improvements across existing API route guides > Note: I didn't work on the guide for additional data validation. Will work on this as part of my next focus on workflows.
156 lines
4.5 KiB
Plaintext
156 lines
4.5 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 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/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} apiTesting testApiUrl="http://localhost:9000/store/hello-world/{id}" testApiMethod="GET" testPathParams={{ "id": "" }}
|
||
import type {
|
||
MedusaRequest,
|
||
MedusaResponse,
|
||
} from "@medusajs/medusa"
|
||
|
||
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 `/store/hello-world/:id/name/:name`, create the file `src/api/store/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`"]
|
||
]
|
||
|
||
```ts title="src/api/store/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights} apiTesting testApiUrl="http://localhost:9000/store/hello-world/{id}/name/{name}" testApiMethod="GET" testPathParams={{ "id": "", "name": "" }}
|
||
import type {
|
||
MedusaRequest,
|
||
MedusaResponse,
|
||
} from "@medusajs/medusa"
|
||
|
||
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`"],
|
||
]
|
||
|
||
```ts title="src/api/store/hello-world/route.ts" highlights={queryHighlights} apiTesting testApiUrl="http://localhost:9000/store/hello-world" testApiMethod="GET" testQueryParams={{ "name": "" }}
|
||
import type {
|
||
MedusaRequest,
|
||
MedusaResponse,
|
||
} from "@medusajs/medusa"
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## 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 = 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.
|
||
|
||
<Note title="Tip">
|
||
|
||
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.
|
||
|
||
</Note>
|
||
|
||
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": "" }}
|
||
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!"
|
||
}
|
||
```
|