docs: general fixes and overall changes (#7258)
* editing halfway * edited second half * adjust starter steps * fix build * typo fix
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
8db62827ac
commit
327e446974
57 files changed
+872
-1849
No files matched your search
@@ -12,7 +12,7 @@ Cross-Origin Resource Sharing (CORS) allows only configured origins to access yo
|
||||
|
||||
### CORS Configurations
|
||||
|
||||
You can configure allowed origins for Store and Admin API Routes using the `store_cors` and `admin_cors` configurations in `medusa-config.js`. Each of these configurations accepts a URL pattern to identify allowed origins.
|
||||
You configure allowed origins for Store and Admin API Routes using the `store_cors` and `admin_cors` configurations in `medusa-config.js`. Each of these configurations accepts a URL pattern to identify allowed origins.
|
||||
|
||||
For example:
|
||||
|
||||
@@ -63,7 +63,7 @@ This disables the CORS middleware on API Routes at the path `/store/custom`.
|
||||
|
||||
## CORS in Custom Routes
|
||||
|
||||
If you create a route that doesn’t start with `/store` or `/admin`, you must apply the CORS middleware manually. Otherwise, all requests to your API route cause a CORS error.
|
||||
If you create a route that doesn’t start with `/store` or `/admin`, you must apply the CORS middleware manually. Otherwise, all requests to your API route lead to a CORS error.
|
||||
|
||||
You can do that in the exported middlewares configurations in `src/api/middlewares.ts`.
|
||||
|
||||
|
||||
@@ -8,12 +8,10 @@ In this chapter, you'll learn about how to add new API routes for each HTTP meth
|
||||
|
||||
## Handlers of HTTP Methods
|
||||
|
||||
You can define a handler function for each HTTP method in a route file. The function’s name is the name of the HTTP method it handles.
|
||||
You can export handler functions for more than one HTTP method in a route file. An API route is created for every HTTP method you export a function for.
|
||||
|
||||
Allowed HTTP methods are: `GET`, `POST`, `DELETE`, `PUT`, `PATCH`, `OPTIONS`, and `HEAD`.
|
||||
|
||||
Creating a route handler function for any of the above HTTP methods exposes a new API route for that method.
|
||||
|
||||
For example, create the file `src/api/store/hello-world/route.ts` with the following content:
|
||||
|
||||
```ts title="src/api/store/hello-world/route.ts"
|
||||
|
||||
@@ -14,11 +14,11 @@ A middleware is a function executed when a request is sent to an API Route.
|
||||
|
||||
## How to Create a Middleware?
|
||||
|
||||
Middlewares are defined in the special file `src/api/middleware.ts`. The file must export an object of middleware configurations.
|
||||
Middlewares are defined in the special file `src/api/middlewares.ts`. The file must export an object of middleware configurations.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="src/api/middleware.ts"
|
||||
```ts title="src/api/middlewares.ts"
|
||||
import { MiddlewaresConfig } from "@medusajs/medusa"
|
||||
|
||||
export const config: MiddlewaresConfig = {
|
||||
@@ -49,19 +49,16 @@ The `matcher` property can be a string or a regular expression.
|
||||
|
||||
### Test Middleware
|
||||
|
||||
To test the middleware, start the application:
|
||||
To test the middleware:
|
||||
|
||||
1. Start the application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Then, send a request to any API route starting with `/store`, such as `localhost:9000/store/products`:
|
||||
|
||||
```bash apiTesting testApiUrl="localhost:9000/store/products" testApiMethod="GET"
|
||||
curl localhost:9000/store/products
|
||||
```
|
||||
|
||||
Once you send the request, you’ll see the following message in the terminal:
|
||||
2. Send a request to any API route starting with `/store`.
|
||||
3. See the following message in the terminal:
|
||||
|
||||
```bash
|
||||
Received a request!
|
||||
@@ -69,13 +66,12 @@ Received a request!
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
## When to Use Middlewares
|
||||
|
||||
<Note type="success" title="Use middlewares when">
|
||||
|
||||
- You want to guard API routes by a custom condition.
|
||||
- You want to protect API routes by a custom condition.
|
||||
- You're modifying the request body.
|
||||
- You're registering custom resources in the Medusa container.
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -101,8 +97,6 @@ You must call the `next` function in the middleware. Otherwise, other middleware
|
||||
|
||||
In addition to the `matcher` configuration, you can restrict which HTTP methods the middleware is applied to.
|
||||
|
||||
The object in the `routes` array accepts the property `method` whose value is either a string or an array of strings. Each string is an allowed HTTP method. If no value is specified, the middlewares are applied to requests of all HTTP methods.
|
||||
|
||||
For example:
|
||||
|
||||
export const highlights = [["7", "", "Apply the middleware only on `POST` requests"]]
|
||||
@@ -114,7 +108,7 @@ export const config: MiddlewaresConfig = {
|
||||
routes: [
|
||||
{
|
||||
matcher: "/store*",
|
||||
method: "POST",
|
||||
method: ["POST", "PUT"],
|
||||
middlewares: [
|
||||
(req, res, next) => {
|
||||
console.log("Received a request!")
|
||||
@@ -127,4 +121,6 @@ export const config: MiddlewaresConfig = {
|
||||
}
|
||||
```
|
||||
|
||||
This applies the middleware only when a `POST` request is sent to an API route path starting with `/store`.
|
||||
The object in the `routes` array accepts the property `method` whose value is one or more HTTP methods to apply the middleware to.
|
||||
|
||||
This applies the middleware only when a `POST` or `PUT` request is sent to an API route path starting with `/store`.
|
||||
@@ -8,9 +8,9 @@ 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.
|
||||
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 an ID that can be passed to the route, create the file `src/api/store/hello-world/[id]/route.ts` with the following content:
|
||||
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`"]
|
||||
@@ -32,13 +32,13 @@ export const GET = (
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
The `MedusaRequest` object has a `params` property. `params` holds the path parameters in key-value pairs.
|
||||
|
||||
### 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.
|
||||
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, you can create an API route at `src/api/store/hello-world/[id]/name/[name]/route.ts`:
|
||||
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`"],
|
||||
@@ -67,7 +67,7 @@ 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.
|
||||
You can access all query parameters in the `query` property of the `MedusaRequest` object.
|
||||
|
||||
For example:
|
||||
|
||||
@@ -95,11 +95,12 @@ export async function GET(
|
||||
|
||||
## 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.
|
||||
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`"],
|
||||
]
|
||||
|
||||
@@ -123,18 +124,16 @@ export const POST = (
|
||||
}
|
||||
```
|
||||
|
||||
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"
|
||||
}'
|
||||
curl -X POST 'http://localhost:9000/store/hello-world' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"name": "John"
|
||||
}'
|
||||
```
|
||||
|
||||
This returns the following JSON object:
|
||||
|
||||
@@ -57,9 +57,7 @@ You can access the logged-in customer’s ID in all API routes starting with `/s
|
||||
|
||||
For example:
|
||||
|
||||
|
||||
|
||||
```ts title="src/api/store/custom/route.ts" highlights={[["16", "", "Access the logged-in customer's ID."]]}
|
||||
```ts title="src/api/store/me/custom/route.ts" highlights={[["16", "", "Access the logged-in customer's ID."]]}
|
||||
import type {
|
||||
MedusaRequest,
|
||||
MedusaResponse,
|
||||
@@ -122,9 +120,9 @@ In the route handler, you resolve the `UserService`, and then use it to retrieve
|
||||
|
||||
To protect custom API Routes that don’t start with `/store/me` or `/admin`, apply one of the following middlewares exported by the `@medusajs/medusa` package on your routes:
|
||||
|
||||
- `authenticate`: only authenticated admin users can access the API Route. You can access the user's ID in the API Route method handler using the `MedusaRequest` object's `user.userId`.
|
||||
- `authenticate`: only authenticated admin users can access the API Route.
|
||||
- `authenticateCustomer`: customer authentication isn’t required, but if a customer is logged in, it attaches their ID to the `MedusaRequest` object's `user.customer_id`.
|
||||
- `requireCustomerAuthentication`: only authenticated customers can access the API Route. You can access the customer's ID in the API Route method handler using the `MedusaRequest` object's `user.customer_id`.
|
||||
- `requireCustomerAuthentication`: only authenticated customers can access the API Route.
|
||||
|
||||
For example:
|
||||
|
||||
|
||||
@@ -1,66 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Request Body Parsers`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this chapter, you’ll learn how to configure request-body parsing and add new parsers.
|
||||
|
||||
## Add a Request-Body Parser
|
||||
|
||||
You can parse request bodies of other content types by adding the parser as a middleware to the routes.
|
||||
|
||||
For example:
|
||||
|
||||
export const parserHighlights = [
|
||||
["13", "", "Add a parser for the `application/x-www-form-urlencoded` content type."]
|
||||
]
|
||||
|
||||
```ts title="src/api/middlewares.ts" highlights={parserHighlights}
|
||||
import type {
|
||||
MiddlewaresConfig,
|
||||
} from "@medusajs/medusa"
|
||||
import {
|
||||
urlencoded,
|
||||
} from "body-parser"
|
||||
|
||||
export const config: MiddlewaresConfig = {
|
||||
routes: [
|
||||
{
|
||||
matcher: "*",
|
||||
middlewares: [
|
||||
urlencoded({ extended: true }),
|
||||
],
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
This adds a parser for the `application/x-www-form-urlencoded` content type and attaches the parsed data to the `MedusaRequest` object’s `body` property.
|
||||
|
||||
---
|
||||
|
||||
## Parse Webhook Body Parameters
|
||||
|
||||
Webhook API Routes may require the `raw` body parser middleware rather than the default `json`.
|
||||
|
||||
To change the default parser, set the `bodyParser` property of a middleware route object to `false`, and pass the preferred body-parser middleware in the `middlewares` property.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="src/api/middlewares.ts" highlights={[["8", "", "Disables the default request-body parser."], ["9", "raw", "Add a new body parser."]]}
|
||||
import { MiddlewaresConfig } from "@medusajs/medusa"
|
||||
import { raw } from "body-parser"
|
||||
|
||||
export const config: MiddlewaresConfig = {
|
||||
routes: [
|
||||
{
|
||||
matcher: "/webhooks*",
|
||||
bodyParser: false,
|
||||
middlewares: [raw({ type: "application/json" })],
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
This changes the request-body parser to use the `raw` middleware on routes starting with `/webhooks`.
|
||||
Reference in new issue
Block a user