docs: update docs across projects following publishable API key change in store routes (#9098)

* docs: update docs across projects following publishable API key change in store routes * rename env variable * move subscribe route out of store
2024-09-16 16:42:08 +03:00
parent ef8dc4087e
commit 58f06be44d
66 changed files with 577 additions and 298 deletions
@@ -12,9 +12,9 @@ An API route is created for every HTTP method you export a handler function for

 Allowed HTTP methods are: `GET`, `POST`, `DELETE`, `PUT`, `PATCH`, `OPTIONS`, and `HEAD`.

-For example, create the file `src/api/store/hello-world/route.ts` with the following content:
+For example, create the file `src/api/hello-world/route.ts` with the following content:

-```ts title="src/api/store/hello-world/route.ts"
+```ts title="src/api/hello-world/route.ts"
 import type {
  MedusaRequest,
  MedusaResponse,
@@ -41,5 +41,5 @@ export const POST = async (

 This adds two API Routes:

- A `GET` route at `http://localhost:9000/store/hello-world`.
- A `POST` route at `http://localhost:9000/store/hello-world`.
+- A `GET` route at `http://localhost:9000/hello-world`.
+- A `POST` route at `http://localhost:9000/hello-world`.
@@ -37,7 +37,7 @@ import type {
 export default defineMiddlewares({
  routes: [
    {
-      matcher: "/store*",
+      matcher: "/custom*",
      middlewares: [
        (
          req: MedusaRequest, 
@@ -59,7 +59,7 @@ The `defineMiddlewares` function accepts a middleware configurations object that
 - `matcher`: a string or regular expression indicating the API route path to apply the middleware on. The regular expression must be compatible with [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
 - `middlewares`: An array of middleware functions.

-In the example above, you define a middleware that logs the message `Received a request!` whenever a request is sent to an API route path starting with `/store`.
+In the example above, you define a middleware that logs the message `Received a request!` whenever a request is sent to an API route path starting with `/custom`.

 ---

@@ -73,7 +73,7 @@ To test the middleware:
 npm run dev
 ```

-2. Send a request to any API route starting with `/store`.
+2. Send a request to any API route starting with `/custom`.
 3. See the following message in the terminal:

 ```bash
@@ -128,7 +128,7 @@ import type {
 export default defineMiddlewares({
  routes: [
    {
-      matcher: "/store/custom/:id",
+      matcher: "/custom/:id",
      middlewares: [
        // ...
      ],
@@ -137,7 +137,7 @@ export default defineMiddlewares({
 })
 ```

-This applies a middleware to the routes defined in the file `src/api/store/custom/[id]/route.ts`.
+This applies a middleware to the routes defined in the file `src/api/custom/[id]/route.ts`.

 ---

@@ -160,7 +160,7 @@ import type {
 export default defineMiddlewares({
  routes: [
    {
-      matcher: "/store*",
+      matcher: "/custom*",
      method: ["POST", "PUT"],
      middlewares: [
        // ...
@@ -172,7 +172,7 @@ export default defineMiddlewares({

 `method`'s value is one or more HTTP methods to apply the middleware to.

-This example applies the middleware only when a `POST` or `PUT` request is sent to an API route path starting with `/store`.
+This example applies the middleware only when a `POST` or `PUT` request is sent to an API route path starting with `/custom`.

 ---

@@ -10,13 +10,13 @@ In this chapter, you’ll learn about path, query, and request body 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:
+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`"]
 ]

-```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": "" }}
+```ts title="src/api/hello-world/[id]/route.ts" highlights={singlePathHighlights}
 import type {
  MedusaRequest,
  MedusaResponse,
@@ -38,14 +38,14 @@ The `MedusaRequest` object has a `params` property. `params` holds the path para

 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:
+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`"]
 ]

-```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": "" }}
+```ts title="src/api/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights}
 import type {
  MedusaRequest,
  MedusaResponse,
@@ -77,7 +77,7 @@ 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": "" }}
+```ts title="src/api/hello-world/route.ts" highlights={queryHighlights}
 import type {
  MedusaRequest,
  MedusaResponse,
@@ -108,7 +108,7 @@ export const bodyHighlights = [
  ["15", "req.body.name", "Access the request body parameter `name`"],
 ]

-```ts title="src/api/store/hello-world/route.ts" highlights={bodyHighlights}
+```ts title="src/api/hello-world/route.ts" highlights={bodyHighlights}
 import type {
  MedusaRequest,
  MedusaResponse,
@@ -138,8 +138,8 @@ The `MedusaRequest` type accepts a type argument that indicates the type of the

 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' \
+```bash
+curl -X POST 'http://localhost:9000/hello-world' \
 -H 'Content-Type: application/json' \
 --data-raw '{
  "name": "John"
@@ -20,7 +20,7 @@ Requests to `/admin` must be user-authenticated to access the route.

 <Note title="Tip">

-Refer to the API Reference for [Admin](https://docs.medusajs.com/api/admin#authentication) and [Store](https://docs.medusajs.com/api/store#authentication) authentication methods.
+Refer to the API Reference for [Admin](!api!/admin#authentication) and [Store](!api!/store#authentication) authentication methods.

 </Note>

@@ -16,7 +16,7 @@ export const jsonHighlights = [
  ["7", "json", "Return a JSON object."]
 ]

-```ts title="src/api/store/custom/route.ts" highlights={jsonHighlights} apiTesting testApiUrl="http://localhost:9000/store/custom" testApiMethod="GET"
+```ts title="src/api/custom/route.ts" highlights={jsonHighlights}
 import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"

 export const GET = async (
@@ -51,7 +51,7 @@ export const statusHighlight = [
  ["7", "status", "Set the response code to `201`."]
 ]

-```ts title="src/api/store/custom/route.ts" highlights={statusHighlight} apiTesting testApiUrl="http://localhost:9000/store/custom" testApiMethod="GET"
+```ts title="src/api/custom/route.ts" highlights={statusHighlight}
 import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"

 export const GET = async (
@@ -8,7 +8,7 @@ In this chapter, you'll learn how to validate request body parameters in your cu

 ## Example Scenario

-Consider you're creating a `POST` API route at `/store/custom`. It accepts two paramters `a` and `b` that are required numbers, and returns their sum.
+Consider you're creating a `POST` API route at `/custom`. It accepts two paramters `a` and `b` that are required numbers, and returns their sum.

 The next steps explain how to add validation to this API route, as an example.

@@ -20,9 +20,9 @@ Medusa uses [Zod](https://zod.dev/) to validate the body parameters of an incomi

 To use Zod to validate your custom schemas, create a `validators.ts` file in any `src/api` subfolder. This file holds Zod schemas for each of your API routes.

-For example, create the file `src/api/store/custom/validators.ts` with the following content:
+For example, create the file `src/api/custom/validators.ts` with the following content:

-```ts title="src/api/store/custom/validators.ts"
+```ts title="src/api/custom/validators.ts"
 import { z } from "zod"

 export const PostStoreCustomSchema = z.object({
@@ -41,7 +41,7 @@ The `PostStoreCustomSchema` variable is a Zod schema that indicates the request

 ## Step 2: Add Validation Middleware

-To use this schema for validating the body parameters of requests to `/store/custom`, use the `validateAndTransformBody` middleware provided by `@medusajs/medusa`. It accepts the Zod schema as a parameter.
+To use this schema for validating the body parameters of requests to `/custom`, use the `validateAndTransformBody` middleware provided by `@medusajs/medusa`. It accepts the Zod schema as a parameter.

 For example, create the file `src/api/middlewares.ts` with the following content:

@@ -50,12 +50,12 @@ import { defineMiddlewares } from "@medusajs/medusa"
 import { 
  validateAndTransformBody,
 } from "@medusajs/medusa/dist/api/utils/validate-body"
-import { PostStoreCustomSchema } from "./store/custom/validators"
+import { PostStoreCustomSchema } from "./custom/validators"

 export default defineMiddlewares({
  routes: [
    {
-      matcher: "/store/custom",
+      matcher: "/custom",
      method: "POST",
      middlewares: [
        validateAndTransformBody(PostStoreCustomSchema),
@@ -65,7 +65,7 @@ export default defineMiddlewares({
 })
 ```

-This applies the `validateAndTransformBody` middleware on `POST` requests to `/store/custom`. It uses the `PostStoreCustomSchema` as the validation schema.
+This applies the `validateAndTransformBody` middleware on `POST` requests to `/custom`. It uses the `PostStoreCustomSchema` as the validation schema.

 ### How the Validation Works

@@ -79,14 +79,14 @@ If a request's body parameters are validated successfully, the middleware sets t

 In your API route, consume the validated body using the `validatedBody` property of `MedusaRequest`.

-For example, create the file `src/api/store/custom/route.ts` with the following content:
+For example, create the file `src/api/custom/route.ts` with the following content:

 export const routeHighlights = [
  ["5", "PostStoreCustomSchemaType", "Infer the request body type from the schema to pass it as a type parameter to `MedusaRequest`."],
  ["14", "", "Access the body parameters using `validatedBody`."]
 ]

-```ts title="src/api/store/custom/route.ts" highlights={routeHighlights}
+```ts title="src/api/custom/route.ts" highlights={routeHighlights}
 import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
 import { z } from "zod"
 import { PostStoreCustomSchema } from "./validators"
@@ -117,7 +117,7 @@ To pass the request body's type as a type parameter to `MedusaRequest`, use Zod'

 ## Test it Out

-To test out the validation, send a `POST` request to `/store/custom`. You can try sending incorrect request body parameters.
+To test out the validation, send a `POST` request to `/custom`. You can try sending incorrect request body parameters.

 For example, if you omit the `a` parameter, you'll receive a `400` response code with the following response data:

@@ -24,7 +24,7 @@ In your resources, such as API routes or workflows, you can resolve Query to fet

 ## Query Example

-For example, create the route `src/api/store/query/route.ts` with the following content:
+For example, create the route `src/api/query/route.ts` with the following content:

 export const exampleHighlights = [
  ["13", "", "Resolve Query from the Medusa container."],
@@ -33,7 +33,7 @@ export const exampleHighlights = [
  ["17", "fields", "An array of the data model’s properties to retrieve in the result."],
 ]

-```ts title="src/api/store/query/route.ts" highlights={exampleHighlights} apiTesting testApiMethod="GET" testApiUrl="http://localhost:9000/store/query" collapsibleLines="1-8" expandButtonLabel="Show Imports"
+```ts title="src/api/query/route.ts" highlights={exampleHighlights} collapsibleLines="1-8" expandButtonLabel="Show Imports"
 import {
  MedusaRequest,
  MedusaResponse,
@@ -19,7 +19,7 @@ export const highlights = [
  ["14", "throwOnError", "Specify that errors occuring during the workflow's execution should be returned, not thrown."],
 ]

-```ts title="src/api/store/workflows/route.ts" highlights={highlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
+```ts title="src/api/workflows/route.ts" highlights={highlights} collapsibleLines="1-6" expandButtonLabel="Show Imports"
 import type {
  MedusaRequest,
  MedusaResponse,
@@ -239,9 +239,9 @@ In the workflow construction function, you first run the `updateProduct` step, t

 You can now use and execute your workflow in your Medusa application.

-To execute the workflow in an API route, create the file `src/api/store/products/[id]/erp/route.ts` with the following content:
+To execute the workflow in an API route, create the file `src/api/products/[id]/erp/route.ts` with the following content:

-```ts title="src/api/store/products/[id]/erp/route.ts"
+```ts title="src/api/products/[id]/erp/route.ts"
 import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
 import updateProductAndErpWorkflow, {
  UpdateProductAndErpWorkflowInput,
@@ -79,7 +79,7 @@ export default myWorkflow

 3. Execute the workflow from a resource, such as an API route:

-```ts title="src/api/store/workflow/route.ts" collapsibleLines="1-6" expandButtonLabel="Show Imports"
+```ts title="src/api/workflow/route.ts" collapsibleLines="1-6" expandButtonLabel="Show Imports"
 import type {
  MedusaRequest,
  MedusaResponse,
@@ -103,10 +103,10 @@ export async function GET(
 npm run dev
 ```

-5. Send a `GET` request to `/store/workflow`:
+5. Send a `GET` request to `/workflow`:

-```bash apiTesting testApiMethod="GET" testApiUrl="http://localhost:9000/store/workflow"
-curl http://localhost:9000/store/workflow
+```bash
+curl http://localhost:9000/workflow
 ```

 In the console, you'll see:
@@ -276,7 +276,7 @@ export const highlights = [
  ["30", "subscribe", "Subscribe to status changes of the workflow execution."],
 ]

-```ts title="src/api/store/workflows/route.ts" highlights={highlights} collapsibleLines="1-11" expandButtonLabel="Show Imports"
+```ts title="src/api/workflows/route.ts" highlights={highlights} collapsibleLines="1-11" expandButtonLabel="Show Imports"
 import type { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
 import myWorkflow from "../../../workflows/hello-world"
 import {