From 522d3ce764357e7db001563344bcdd3433d8fe03 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Sun, 6 Oct 2024 19:51:08 +0300 Subject: [PATCH] docs: improvements to API reference intro sections (#9397) - Improve intro sections of API reference to utilize divided columns - Improve the content of the intro sections - Add a new Workflows section to explain the workflows badge and how to use it - Fixes to headings and add anchor for copying the link to a section - Fixes responsiveness of intro sections on mobile devices - Other: fix loading not showing when a sidebar category is opened. Closes DOCS-932, DOCS-934, DOCS-937 Preview: https://api-reference-v2-git-docs-api-ref-intro-fixes-medusajs.vercel.app/v2/api/store --- www/apps/api-reference/app/_mdx/admin.mdx | 538 +++++++++++++++--- .../app/_mdx/client-libraries.mdx | 9 +- www/apps/api-reference/app/_mdx/store.mdx | 517 ++++++++++++++--- www/apps/api-reference/app/admin/page.tsx | 26 +- www/apps/api-reference/app/store/page.tsx | 25 +- .../components/MDXComponents/H2/index.tsx | 6 +- .../components/Section/Container/index.tsx | 7 +- .../components/Section/index.tsx | 1 + .../api-reference/components/Tags/index.tsx | 1 + .../api-reference/layouts/Divided/index.tsx | 6 +- .../DividedMarkdown/Sections/index.tsx | 10 + .../layouts/DividedMarkdown/index.tsx | 30 + www/apps/api-reference/next.config.mjs | 12 +- www/apps/api-reference/package.json | 2 + .../src/components/Heading/H1/index.tsx | 19 + .../src/components/Heading/H2/index.tsx | 32 ++ .../src/components/Heading/H3/index.tsx | 30 + .../src/components/Heading/H4/index.tsx | 14 + .../docs-ui/src/components/Heading/index.tsx | 4 + .../src/components/MDXComponents/index.tsx | 81 +-- .../Sidebar/Item/Category/index.tsx | 11 +- www/packages/docs-ui/src/components/index.ts | 1 + .../src/hooks/use-active-on-scroll/index.tsx | 15 +- .../docs-ui/src/layouts/main-content.tsx | 5 +- www/packages/docs-ui/src/layouts/wide.tsx | 1 + www/packages/types/src/sidebar.ts | 1 + www/yarn.lock | 2 + 27 files changed, 1130 insertions(+), 276 deletions(-) create mode 100644 www/apps/api-reference/layouts/DividedMarkdown/Sections/index.tsx create mode 100644 www/apps/api-reference/layouts/DividedMarkdown/index.tsx create mode 100644 www/packages/docs-ui/src/components/Heading/H1/index.tsx create mode 100644 www/packages/docs-ui/src/components/Heading/H2/index.tsx create mode 100644 www/packages/docs-ui/src/components/Heading/H3/index.tsx create mode 100644 www/packages/docs-ui/src/components/Heading/H4/index.tsx create mode 100644 www/packages/docs-ui/src/components/Heading/index.tsx diff --git a/www/apps/api-reference/app/_mdx/admin.mdx b/www/apps/api-reference/app/_mdx/admin.mdx index 4bb62b8419626..61e51f23a36d0 100644 --- a/www/apps/api-reference/app/_mdx/admin.mdx +++ b/www/apps/api-reference/app/_mdx/admin.mdx @@ -1,9 +1,23 @@ import { Feedback, CodeTabs, CodeTab } from "docs-ui" import SectionContainer from "@/components/Section/Container" +import DividedMarkdownLayout from "@/layouts/DividedMarkdown" +import { + DividedMarkdownContent, + DividedMarkdownCode +} from "@/layouts/DividedMarkdown/Sections" +import Section from "@/components/Section" import formatReportLink from "@/utils/format-report-link" +import ClientLibraries from "./client-libraries.mdx" + +
+ + + + + Medusa v2.0 is in development and not suitable for production @@ -12,7 +26,7 @@ change, so please use it with caution. -This API reference includes Medusa's Admin APIs, which are REST APIs exposed by the Medusa application. They are used to perform admin functionalities or create an admin dashboard to access and manipulate your commerce store's data. +This API reference includes Medusa v2's Admin APIs, which are REST APIs exposed by the Medusa application. They are used to perform admin functionalities or create an admin dashboard to access and manipulate your commerce store's data. All API Routes are prefixed with `/admin`. So, during development, the API Routes will be available under the path `http://localhost:9000/admin`. For production, replace `http://localhost:9000` with your Medusa application URL. @@ -28,25 +42,49 @@ All API Routes are prefixed with `/admin`. So, during development, the API Route vertical={true} /> + + + + + + + + + + + + + + ## Authentication There are three ways to send authenticated requests to the Medusa server: Using a JWT token in a bearer authorization header, using an admin user's API token, or using a cookie session ID. -### Bearer Authorization with JWT Tokens +### 1. Bearer Authorization with JWT Tokens Use a JWT token in a request's bearer authorization header to send authenticated requests. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications. + + + + + + + + #### How to Obtain the JWT Token -JWT tokens are obtained by sending a request to the authentication route passing it the user's email and password in the request body. +To obtain a JWT token, send a request to the [authentication route](#auth_postactor_typeauth_provider) passing it the user's email and password in the request body. -For example: + -```bash + + +```bash title="Obtain JWT token" curl -X POST '{backend_url}/auth/user/emailpass' \ -H 'Content-Type: application/json' \ --data-raw '{ @@ -55,61 +93,122 @@ curl -X POST '{backend_url}/auth/user/emailpass' \ }' ``` + + + + + + + + If authenticated successfully, an object is returned in the response with the property `token` being the JWT token. -Learn more about the authentication route [here](#auth_postactor_typeauth_provider) + + + + +```json title="Example response" +{ + "token": "123..." +} +``` + + + + + + + + #### How to Use the JWT Token -Pass the JWT token in the authorization bearer header: +To use the JWT token, pass it in the authorization bearer header. + + + -```bash +```bash title="Use JWT token" Authorization: Bearer {jwt_token} ``` ---- + + + + + -### API Token + + +### 2. API Token Use a user's API Token to send authenticated requests. + + + + + + + + +#### How to Create an API Token for a User + +Use the [Create API Key API Route](#api-keys_postapikeys) to create an API token. + -This authentication method relies on using another authentication method first, as you must be an authenticated user to create an API token. +You must be an authenticated user to create an API token. -#### How to Create an API Token for a User +An `api_key` object is returned in the response. You need its `token` property. + + -Use the [Create API Key API Route](#api-keys_postapikeys) to create an API token: + -```bash -curl --location 'localhost:9000/admin/api-keys' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer {jwt_token}' \ +```bash title="Create API token" +curl -X POST 'localhost:9000/admin/api-keys' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer {jwt_token}' \ --data '{ "title": "my token", "type": "secret" }' ``` -{/* TODO add a link to the API key object */} + -An `api_key` object is returned in the response. You need its `token` property. + + + + + #### How to Use the API Token -The API token can be used by providing it in a basic authorization header: +Use the API token by passing it in a basic authorization header. + + -```bash + + +```bash title="Use API token" Authorization: Basic {api_key_token} ``` ---- + + + + + -### Cookie Session ID + + +### 3. Cookie Session ID When you authenticate a user and create a cookie session ID for them, the cookie session ID is passed automatically when sending the request from the browser, or with tools like Postman. @@ -117,49 +216,97 @@ When you authenticate a user and create a cookie session ID for them, the cookie To obtain a cookie session ID, you must have a [JWT token for bearer authentication](#bearer-authorization-with-jwt-tokens). -{/* TODO add a link to the session authentication route. */} + + + + + -Then, send a request to the session authentication API route. To view the cookie session ID, pass the `-v` option to the `curl` command: + -```bash +Then, send a request to the session authentication API route. + +To view the cookie session ID, pass the `-v` option to the `curl` command. + + + + + +```bash title="Obtain cookie session" curl -v -X POST '{backend_url}/auth/session' \ --header 'Authorization: Bearer {jwt_token}' ``` + + + + + + + The headers will be logged in the terminal as well as the response. You -should find in the headers a Cookie header similar to this: +should find in the headers a Cookie header. + -```bash -Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM; + + +```bash title="Logged cookie session" +Set-Cookie: connect.sid=s%3A2Bu8B...; ``` + + + + + + + + #### How to Use the Cookie Session ID in cURL Copy the value after `connect.sid` (without the `;` at the end) and pass -it as a cookie in subsequent requests as the following: +it as a cookie in subsequent requests. + + + -```bash +```bash title="Use cookie session" curl '{backend_url}/admin/products' \ -H 'Cookie: connect.sid={sid}' ``` - Where `{sid}` is the value of `connect.sid` that you copied. -#### Including Credentials in the Fetch API + + + + + + + If you're sending requests using JavaScript's Fetch API, you must pass the `credentials` option -with the value `include` to all the requests you're sending. For example: +with the value `include` to all the requests you're sending. -```js + + + + +```js title="Include credentials in fetch" fetch(`/admin/products`, { credentials: "include", }) ``` + + + + + + /admin/products`, { vertical={true} /> + + + + + + ## HTTP Compression + + + + + + + + If you've enabled HTTP Compression in your Medusa configurations, and you want to disable it for some requests, you can pass the `x-no-compression` -header in your requests: +header in your requests. + + -```bash + + +```bash title="Enable HTTP compression" x-no-compression: true ``` + + + + + + + + + + + + ## Select Fields and Relations + + + + + + + + Many API Routes accept a `fields` query that allows you to select which fields and relations should be returned in a record. Fields and relations are separated by a comma `,`. -For example: + + + -```bash +```bash title="Select fields" curl 'localhost:9000/admin/products?fields=title,handle' \ -H 'Authorization: Bearer {jwt_token}' ``` This returns only the `title` and `handle` fields of a product. + + + + + + + + ### Fields Operator By default, only the selected fields and relations are returned in the response. @@ -225,106 +420,182 @@ Before every field or relation, you can pass one of the following operators to c - `+`: Add the field to the fields returned by default. For example, `+title` returns the `title` field along with the fields returned by default. - `-`: Remove the field from the fields returned by default. For example, `-title` removes the `title` field from the fields returned by default. + + + + + + + + ### Select Relations -To select a relation, pass to `fields` the relation name prefixed by `*`. For example: +To select a relation, pass to `fields` the relation name prefixed by `*`. + + -```bash + + +```bash title="Select relations" curl 'localhost:9000/admin/products?fields=*variants' \ -H 'Authorization: Bearer {jwt_token}' ``` This returns the variants of each product. + + + + + + + + ### Select Fields in a Relation The `*` prefix selects all fields of the relation's data model. + + + + + + + + To select a specific field, pass a `.` suffix instead of the `*` prefix. For example, `variants.title`. To specify multiple fields, pass each of the fields with the `.` format, separated by a comma. -For example: + + + -```bash +```bash title="Select relation's fields" curl 'localhost:9000/admin/products?fields=variants.title,variants.sku' \ -H 'Authorization: Bearer {jwt_token}' ``` This returns the variants of each product, but the variants only have their `id`, `title`, and `sku` fields. The `id` is always included. + + + + + + + + ## Query Parameter Types This section covers how to pass some common data types as query parameters. +This is useful if you're sending requests to the API Routes using cURL or Postman. + + + + + + + + ### Strings You can pass a string value in the form of `=`. + -For example: - + -```bash +```bash title="String filter" curl "http://localhost:9000/admin/products?title=Shirt" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + + + + If the string has any characters other than letters and numbers, you must encode them. For example, if the string has spaces, you can encode the space with `+` or -`%20`: +`%20`. + +You can use tools like [this one](https://www.urlencoder.org/) to learn how +a value can be encoded. + + + -```bash +```bash title="Encoded string filter" curl "http://localhost:9000/admin/products?title=Blue%20Shirt" \ -H 'Authorization: Bearer {jwt_token}' ``` + -You can use tools like [this one](https://www.urlencoder.org/) to learn how -a value can be encoded. + + -### Integers + +### Integers You can pass an integer value in the form of `=`. + -For example: + - -```bash +```bash title="Integer filter" curl "http://localhost:9000/admin/products?offset=1" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + + + + ### Boolean You can pass a boolean value in the form of `=`. + -For example: - + -```bash +```bash title="Boolean filter" curl "http://localhost:9000/admin/products?is_giftcard=true" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + + + + ### Date and DateTime @@ -332,28 +603,42 @@ curl "http://localhost:9000/admin/products?is_giftcard=true" \ You can pass a date value in the form `=`. The date must be in the format `YYYY-MM-DD`. + -For example: - + -```bash +```bash title="Date filter" curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + + + + You can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed. + -For example: - + -```bash +```bash title="Date and time filter" curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17T07:22:30Z" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + + + + ### Array @@ -362,20 +647,26 @@ Each array value must be passed as a separate query parameter in the form `[]=`. You can also specify the index of each parameter in the brackets `[0]=`. + -For example: + - -```bash +```bash title="Array filter" curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" \ -H 'Authorization: Bearer {jwt_token}' ``` - Note that the `-g` parameter passed to `curl` disables errors being thrown for using the brackets. Read more [here](https://curl.se/docs/manpage.html#-g). + + + + + + + ### Object @@ -383,15 +674,21 @@ for using the brackets. Read more Object parameters must be passed as separate query parameters in the form `[]=`. + -For example: - + -```bash +```bash title="Object filter" curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17&created_at[$gt]=2022-09-17" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + + + + + + + + + ## Pagination ### Query Parameters @@ -415,20 +718,35 @@ curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17&created In listing API Routes, such as list customers or list products, you can control the pagination using the query parameters `limit` and `offset`. + + + + + + + `limit` is used to specify the maximum number of items to be returned in the response. `offset` is used to specify how many items to skip before returning the resulting records. Use the `offset` query parameter to change between pages. For example, if the limit is `50`, at page `1` the offset should be `0`; at page `2` the offset should be `50`, and so on. + -For example: + -```bash +```bash title="Pagination query parameters" curl "http://localhost:9000/admin/products?limit=5" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + + + + ### Response Fields @@ -445,6 +763,13 @@ there are three pagination-related fields returned: For example, if the `count` is `100` and the `limit` is `50`, divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`. + + + + + + + ### Sort Order @@ -452,26 +777,45 @@ For example, if the `count` is `100` and the `limit` is `50`, divide the The `order` field (available on API Routes that support pagination) allows you to sort the retrieved items by a field of that item. -For example, pass the query parameter `order=created_at` to sort products by their `created_at` field: + -```bash + + +```bash title="Ascending sort by a field" curl "http://localhost:9000/admin/products?order=created_at" \ -H 'Authorization: Bearer {jwt_token}' ``` +This sorts the products by their `created_at` field in the ascending order. + + + + + + + + + By default, the sort direction is ascending. To change it to descending, pass a dash (`-`) before the field name. -For example: + + + -```bash +```bash title="Descending sort by a field" curl "http://localhost:9000/admin/products?order=-created_at" \ -H 'Authorization: Bearer {jwt_token}' ``` - This sorts the products by their `created_at` field in the descending order. + + + + + + - \ No newline at end of file + + + + + + + + + + +## Workflows + +While browsing this reference, you'll find some API routes mention what workflow is used in them. + +If you click on the workflow, you'll view a reference of that workflow, including its hooks. + +This is useful if you want to extend an API route and pass additional data or perform custom actions. + +Refer to [this guide](https://docs.medusajs.com/v2/customization/extend-models/extend-create-product) to find an example of extending an API route. + + + + + + + + + +
\ No newline at end of file diff --git a/www/apps/api-reference/app/_mdx/client-libraries.mdx b/www/apps/api-reference/app/_mdx/client-libraries.mdx index b85d8aaea3255..a722782bb551e 100644 --- a/www/apps/api-reference/app/_mdx/client-libraries.mdx +++ b/www/apps/api-reference/app/_mdx/client-libraries.mdx @@ -1,20 +1,21 @@ +import { H3 } from "docs-ui" import Space from "@/components/Space" import DownloadFull from "@/components/DownloadFull" -### Just Getting Started? +

Just Getting Started?

-Check out the [quickstart guide](https://docs.medusajs.com/create-medusa-app). +Check out the [Medusa v2 Documentation](https://docs.medusajs.com/v2). -Support for v2 API Routes is coming soon in Medusa JS Client and Medusa React. +JavaScript client libraries are coming soon for Medusa v2. ### Download Full Reference -Download this reference as an OpenApi YAML file. You can import this file to tools like Postman and start sending requests directly to your Medusa backend. +Download this reference as an OpenApi YAML file. You can import this file to tools like Postman and start sending requests directly to your Medusa application. \ No newline at end of file diff --git a/www/apps/api-reference/app/_mdx/store.mdx b/www/apps/api-reference/app/_mdx/store.mdx index 0a2899bf99d3d..393d32136070e 100644 --- a/www/apps/api-reference/app/_mdx/store.mdx +++ b/www/apps/api-reference/app/_mdx/store.mdx @@ -1,10 +1,23 @@ - -import { Feedback, CodeTabs, CodeTab } from "docs-ui" import SectionContainer from "@/components/Section/Container" +import DividedMarkdownLayout from "@/layouts/DividedMarkdown" +import { + DividedMarkdownContent, + DividedMarkdownCode +} from "@/layouts/DividedMarkdown/Sections" +import Section from "@/components/Section" +import { Feedback, CodeTabs, CodeTab } from "docs-ui" import formatReportLink from "@/utils/format-report-link" +import ClientLibraries from "./client-libraries.mdx" + +
+ + + + + Medusa v2.0 is in development and not suitable for production @@ -13,7 +26,7 @@ change, so please use it with caution. -This API reference includes Medusa's Store APIs, which are REST APIs exposed by the Medusa application. They are used to create a storefront for your commerce store, such as a webshop or a commerce mobile app. +This API reference includes Medusa v2's Store APIs, which are REST APIs exposed by the Medusa application. They are used to create a storefront for your commerce store, such as a webshop or a commerce mobile app. All API Routes are prefixed with `/store`. So, during development, the API Routes will be available under the path `http://localhost:9000/store`. For production, replace `http://localhost:9000` with your Medusa application URL. @@ -29,25 +42,49 @@ All API Routes are prefixed with `/store`. So, during development, the API Route vertical={true} /> + + + + + + + + + + + + + + ## Authentication There are two ways to send authenticated requests to the Medusa application: Using a JWT token or using a Cookie Session ID. -### Bearer Authorization with JWT Tokens +### 1. Bearer Authorization with JWT Tokens Use a JWT token in a request's bearer authorization header to send authenticated requests. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications. + + + + + + + + #### How to Obtain the JWT Token -JWT tokens are obtained by sending a request to the authentication route passing it the customer's email and password in the request body. +To obtain a JWT token, send a request to the [authentication route](#auth_postactor_typeauth_provider) passing it the customer's email and password in the request body. + + -For example: + -```bash +```bash title="Obtain JWT token" curl -X POST '{backend_url}/auth/customer/emailpass' \ -H 'Content-Type: application/json' \ --data-raw '{ @@ -56,22 +93,55 @@ curl -X POST '{backend_url}/auth/customer/emailpass' \ }' ``` + + + + + + + + If authenticated successfully, an object is returned in the response with the property `token` being the JWT token. -Learn more about the authentication route [here](#auth_postactor_typeauth_provider) + + + + +```json title="Example response" +{ + "token": "123..." +} +``` + + + + + + + + #### How to Use the JWT Token -Pass the JWT token in the authorization bearer header: +To use the JWT token, pass it in the authorization bearer header. + + + -```bash +```bash title="Use JWT token" Authorization: Bearer {jwt_token} ``` ---- + + + -### Cookie Session ID + + + + +### 2. Cookie Session ID When you authenticate a customer and create a cookie session ID for them, the cookie session ID is passed automatically when sending the request from the browser, or with tools like Postman. @@ -81,47 +151,99 @@ To obtain a cookie session ID, you must have a [JWT token for bearer authenticat {/* TODO add a link to the session authentication route. */} -Then, send a request to the session authentication API route. To view the cookie session ID, pass the `-v` option to the `curl` command: + + + + + + + + +Then, send a request to the session authentication API route. -```bash +To view the cookie session ID, pass the `-v` option to the `curl` command. + + + + + +```bash title="Obtain cookie session" curl -v -X POST '{backend_url}/auth/session' \ --header 'Authorization: Bearer {jwt_token}' ``` + + + + + + + The headers will be logged in the terminal as well as the response. You -should find in the headers a Cookie header similar to this: +should find in the headers a Cookie header. + -```bash -Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM; + + +```bash title="Logged cookie session" +Set-Cookie: connect.sid=s%3A2Bu8B...; ``` + + + + + + + + #### How to Use the Cookie Session ID in cURL Copy the value after `connect.sid` (without the `;` at the end) and pass -it as a cookie in subsequent requests as the following: +it as a cookie in subsequent requests. + + + -```bash +```bash title="Use cookie session" curl '{backend_url}/store/products' \ -H 'Cookie: connect.sid={sid}' ``` - Where `{sid}` is the value of `connect.sid` that you copied. + + + + + + + + #### Including Credentials in the Fetch API If you're sending requests using JavaScript's Fetch API, you must pass the `credentials` option -with the value `include` to all the requests you're sending. For example: +with the value `include` to all the requests you're sending. + + + + -```js +```js title="Include credentials in fetch" fetch(`/store/products`, { credentials: "include", }) ``` + + + + + + /store/products`, { vertical={true} /> + + + + + + ## Publishable API Key You must pass a publishable API key in the header of your requests to the store API routes. @@ -154,17 +282,33 @@ Create a publishable API key either using the [admin REST APIs](https://docs.med ### How to Use a Publishable API Key + + + + + + + + You pass the publishable API key in the header `x-publishable-api-key` in all your requests to the store APIs. -For example: + + + -```bash +```bash title="Use publishable API key" curl 'http://localhost:9000/store/products' \ -H 'x-publishable-api-key: {your_publishable_api_key}' ``` Where `{your_publishable_api_key}` is the token of the publishable API key. + + + + + + + + + + + + ## HTTP Compression + + + + + + + + If you've enabled HTTP Compression in your Medusa configurations, and you want to disable it for some requests, you can pass the `x-no-compression` -header in your requests: +header in your requests. + + -```bash + + +```bash title="Enable HTTP compression" x-no-compression: true ``` + + + + + + + + + + + + ## Select Fields and Relations + + + + + + + + Many API Routes accept a `fields` query that allows you to select which fields and relations should be returned in a record. Fields and relations are separated by a comma `,`. -For example: + + + -```bash +```bash title="Select fields" curl 'localhost:9000/store/products?fields=title,handle' ``` This returns only the `title` and `handle` fields of a product. + + + + + + + + ### Fields Operator By default, only the selected fields and relations are returned in the response. @@ -229,32 +421,68 @@ Before every field or relation, you can pass one of the following operators to c - `+`: Add the field to the fields returned by default. For example, `+title` returns the `title` field along with the fields returned by default. - `-`: Remove the field from the fields returned by default. For example, `-title` removes the `title` field from the fields returned by default. + + + + + + + + ### Select Relations -To select a relation, pass to `fields` the relation name prefixed by `*`. For example: +To select a relation, pass to `fields` the relation name prefixed by `*`. + + -```bash + + +```bash title="Select relations" curl 'localhost:9000/store/products?fields=*variants' ``` This returns the variants of each product. + + + + + + + + ### Select Fields in a Relation The `*` prefix selects all fields of the relation's data model. + + + + + + + + To select a specific field, pass a `.` suffix instead of the `*` prefix. For example, `variants.title`. To specify multiple fields, pass each of the fields with the `.` format, separated by a comma. -For example: + + + -```bash +```bash title="Select relation's fields" curl 'localhost:9000/store/products?fields=variants.title,variants.sku' ``` This returns the variants of each product, but the variants only have their `id`, `title`, and `sku` fields. The `id` is always included. + + + + + + + + + + + + ## Query Parameter Types This section covers how to pass some common data types as query parameters. -This is useful if you're sending requests to the API Routes and not using -our JS Client. For example, when using cURL or Postman. +This is useful if you're sending requests to the API Routes using cURL or Postman. + + + + + + + + ### Strings You can pass a string value in the form of `=`. + -For example: - + -```bash +```bash title="String filter" curl "http://localhost:9000/store/products?title=Shirt" ``` + + + + + + + If the string has any characters other than letters and numbers, you must encode them. For example, if the string has spaces, you can encode the space with `+` or -`%20`: +`%20`. + +You can use tools like [this one](https://www.urlencoder.org/) to learn how +a value can be encoded. + -```bash + + +```bash title="Encoded string filter" curl "http://localhost:9000/store/products?title=Blue%20Shirt" ``` + -You can use tools like [this one](https://www.urlencoder.org/) to learn how -a value can be encoded. + + + + + ### Integers You can pass an integer value in the form of `=`. + -For example: + - -```bash +```bash title="Integer filter" curl "http://localhost:9000/store/products?offset=1" ``` + + + + + + + ### Boolean You can pass a boolean value in the form of `=`. + -For example: - + -```bash +```bash title="Boolean filter" curl "http://localhost:9000/store/products?is_giftcard=true" ``` + + + + + + + ### Date and DateTime @@ -342,26 +614,40 @@ curl "http://localhost:9000/store/products?is_giftcard=true" You can pass a date value in the form `=`. The date must be in the format `YYYY-MM-DD`. + -For example: - + -```bash +```bash title="Date filter" curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17" ``` + + + + + + + You can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed. + -For example: + - -```bash +```bash title="Date and time filter" curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17T07:22:30Z" ``` + + + + + + + ### Array @@ -370,19 +656,25 @@ Each array value must be passed as a separate query parameter in the form `[]=`. You can also specify the index of each parameter in the brackets `[0]=`. + -For example: - + -```bash +```bash title="Array filter" curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" ``` - Note that the `-g` parameter passed to `curl` disables errors being thrown for using the brackets. Read more [here](https://curl.se/docs/manpage.html#-g). + + + + + + + ### Object @@ -390,14 +682,20 @@ for using the brackets. Read more Object parameters must be passed as separate query parameters in the form `[]=`. + -For example: - + -```bash +```bash title="Object filter" curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17&created_at[$gt]=2022-09-17" ``` + + + + + + + + + + + + ## Pagination @@ -422,19 +726,34 @@ curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17&created In listing API Routes, such as list products, you can control the pagination using the query parameters `limit` and `offset`. + + + + + + + `limit` is used to specify the maximum number of items to be returned in the response. `offset` is used to specify how many items to skip before returning the resulting records. Use the `offset` query parameter to change between pages. For example, if the limit is `50`, at page `1` the offset should be `0`; at page `2` the offset should be `50`, and so on. + -For example: + -```bash -curl "http://localhost:9000/store/products?limit=5" +```bash title="Pagination query parameters" +curl "http://localhost:9000/store/products?limit=5&offset=0" ``` + + + + + + + ### Response Fields @@ -451,6 +770,13 @@ there are three pagination-related fields returned: For example, if the `count` is `100` and the `limit` is `50`, divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`. + + + + + + + ### Sort Order @@ -458,24 +784,43 @@ For example, if the `count` is `100` and the `limit` is `50`, divide the The `order` field (available on API Routes that support pagination) allows you to sort the retrieved items by a field of that item. -For example, pass the query parameter `order=created_at` to sort products by their `created_at` field: + -```bash + + +```bash title="Ascending sort by a field" curl "http://localhost:9000/store/products?order=created_at" ``` +This sorts the products by their `created_at` field in the ascending order. + + + + + + + + + By default, the sort direction is ascending. To change it to descending, pass a dash (`-`) before the field name. -For example: + -```bash + + +```bash title="Descending sort by a field" curl "http://localhost:9000/store/products?order=-created_at" ``` - This sorts the products by their `created_at` field in the descending order. + + + + + + - \ No newline at end of file + + + + + + +## Workflows + +While browsing this reference, you'll find some API routes mention what workflow is used in them. + +If you click on the workflow, you'll view a reference of that workflow, including its hooks. + +This is useful if you want to extend an API route and pass additional data or perform custom actions. + +Refer to [this guide](https://docs.medusajs.com/v2/customization/extend-models/extend-create-product) to find an example of extending an API route. + + + + + + + + + +
\ No newline at end of file diff --git a/www/apps/api-reference/app/admin/page.tsx b/www/apps/api-reference/app/admin/page.tsx index 11c6875360279..7c27b2652d3d2 100644 --- a/www/apps/api-reference/app/admin/page.tsx +++ b/www/apps/api-reference/app/admin/page.tsx @@ -1,31 +1,17 @@ import AreaProvider from "@/providers/area" -import AdminContentV2 from "../_mdx/admin.mdx" -import ClientLibrariesV2 from "../_mdx/client-libraries.mdx" -import Section from "@/components/Section" +import AdminContent from "../_mdx/admin.mdx" import Tags from "@/components/Tags" -import DividedLayout from "@/layouts/Divided" import PageTitleProvider from "@/providers/page-title" +import { H1 } from "docs-ui" const ReferencePage = async () => { return ( -

+

Medusa V2 Admin API Reference -

- - - - } - codeContent={ -
- -
- } - className="flex-col-reverse" - /> + + @@ -37,7 +23,7 @@ export default ReferencePage export function generateMetadata() { return { title: `Medusa Admin API Reference`, - description: `REST API reference for the Medusa admin API. This reference includes code snippets and examples for Medusa JS Client and cURL.`, + description: `REST API reference for the Medusa v2 admin API, with code snippets and examples.`, metadataBase: process.env.NEXT_PUBLIC_BASE_URL, } } diff --git a/www/apps/api-reference/app/store/page.tsx b/www/apps/api-reference/app/store/page.tsx index a14bd75566a26..be5006eb33c94 100644 --- a/www/apps/api-reference/app/store/page.tsx +++ b/www/apps/api-reference/app/store/page.tsx @@ -1,30 +1,17 @@ import AreaProvider from "@/providers/area" -import StoreContentV2 from "../_mdx/store.mdx" -import ClientLibrariesV2 from "../_mdx/client-libraries.mdx" -import Section from "@/components/Section" +import StoreContent from "../_mdx/store.mdx" import Tags from "@/components/Tags" -import DividedLayout from "@/layouts/Divided" import PageTitleProvider from "@/providers/page-title" +import { H1 } from "docs-ui" const ReferencePage = async () => { return ( -

+

Medusa V2 Store API Reference -

- - - - } - codeContent={ -
- -
- } - /> + + @@ -36,7 +23,7 @@ export default ReferencePage export function generateMetadata() { return { title: `Medusa Store API Reference`, - description: `REST API reference for the Medusa store API. This reference includes code snippets and examples for Medusa JS Client and cURL.`, + description: `REST API reference for the Medusa v2 store API, with code snippets and examples.`, metadataBase: process.env.NEXT_PUBLIC_BASE_URL, } } diff --git a/www/apps/api-reference/components/MDXComponents/H2/index.tsx b/www/apps/api-reference/components/MDXComponents/H2/index.tsx index 0f74773514e1e..ec148b3a223d8 100644 --- a/www/apps/api-reference/components/MDXComponents/H2/index.tsx +++ b/www/apps/api-reference/components/MDXComponents/H2/index.tsx @@ -1,6 +1,6 @@ "use client" -import { useScrollController, useSidebar } from "docs-ui" +import { useScrollController, useSidebar, H2 as UiH2 } from "docs-ui" import { useEffect, useMemo, useRef, useState } from "react" import getSectionId from "../../../utils/get-section-id" @@ -39,9 +39,9 @@ const H2 = ({ children, ...props }: H2Props) => { }, [id]) return ( -

+ {children} -

+ ) } diff --git a/www/apps/api-reference/components/Section/Container/index.tsx b/www/apps/api-reference/components/Section/Container/index.tsx index 0394e510620ab..83bb64b34980b 100644 --- a/www/apps/api-reference/components/Section/Container/index.tsx +++ b/www/apps/api-reference/components/Section/Container/index.tsx @@ -14,9 +14,12 @@ const SectionContainer = forwardRef( ref ) { return ( -
+
{children} - {!noDivider && } + {!noDivider && }
) } diff --git a/www/apps/api-reference/components/Section/index.tsx b/www/apps/api-reference/components/Section/index.tsx index a6be97f98e07f..288cf926efb07 100644 --- a/www/apps/api-reference/components/Section/index.tsx +++ b/www/apps/api-reference/components/Section/index.tsx @@ -19,6 +19,7 @@ const Section = ({ rootElm: sectionRef.current || undefined, enable: checkActiveOnScroll, useDefaultIfNoActive: false, + maxLevel: 2, }) const { setActivePath } = useSidebar() const router = useRouter() diff --git a/www/apps/api-reference/components/Tags/index.tsx b/www/apps/api-reference/components/Tags/index.tsx index bd680d7e03567..f38f3e3a6033c 100644 --- a/www/apps/api-reference/components/Tags/index.tsx +++ b/www/apps/api-reference/components/Tags/index.tsx @@ -90,6 +90,7 @@ const Tags = () => { title: tag.name, children: childItems, loaded: childItems.length > 0, + showLoadingIfEmpty: true, onOpen: () => { if (location.hash !== tagPathName) { router.push(`#${tagPathName}`, { diff --git a/www/apps/api-reference/layouts/Divided/index.tsx b/www/apps/api-reference/layouts/Divided/index.tsx index 837d0000c7566..a66ec4dd6d27f 100644 --- a/www/apps/api-reference/layouts/Divided/index.tsx +++ b/www/apps/api-reference/layouts/Divided/index.tsx @@ -1,12 +1,13 @@ import clsx from "clsx" import { forwardRef } from "react" -type DividedLayoutProps = { +export type DividedLayoutProps = { mainContent: React.ReactNode codeContent: React.ReactNode className?: string mainContentClassName?: string codeContentClassName?: string + addYSpacing?: boolean } const DividedLayout = forwardRef( @@ -17,6 +18,7 @@ const DividedLayout = forwardRef( className, mainContentClassName, codeContentClassName, + addYSpacing = false, }, ref ) { @@ -24,6 +26,7 @@ const DividedLayout = forwardRef(
(
diff --git a/www/apps/api-reference/layouts/DividedMarkdown/Sections/index.tsx b/www/apps/api-reference/layouts/DividedMarkdown/Sections/index.tsx new file mode 100644 index 0000000000000..ca6e7204de986 --- /dev/null +++ b/www/apps/api-reference/layouts/DividedMarkdown/Sections/index.tsx @@ -0,0 +1,10 @@ +type DividedMarkdownSectionProps = { + children: React.ReactElement[] +} + +const DividedMarkdownSection = ({ children }: DividedMarkdownSectionProps) => { + return <>{children} +} + +export const DividedMarkdownContent = DividedMarkdownSection +export const DividedMarkdownCode = DividedMarkdownSection diff --git a/www/apps/api-reference/layouts/DividedMarkdown/index.tsx b/www/apps/api-reference/layouts/DividedMarkdown/index.tsx new file mode 100644 index 0000000000000..dd3960c8ada06 --- /dev/null +++ b/www/apps/api-reference/layouts/DividedMarkdown/index.tsx @@ -0,0 +1,30 @@ +import React from "react" +import DividedLayout, { DividedLayoutProps } from "../Divided" + +type DividedMarkdownLayoutProps = { + children: React.ReactNode +} & Omit + +const DividedMarkdownLayout = ({ + children, + ...props +}: DividedMarkdownLayoutProps) => { + const childArr = React.isValidElement(children) + ? [children] + : Array.isArray(children) + ? children + : [] + + if (!childArr.length) { + return <> + } + + const contentElm = childArr[0] + const codeElm = childArr.length > 1 ? childArr[1] : <> + + return ( + + ) +} + +export default DividedMarkdownLayout diff --git a/www/apps/api-reference/next.config.mjs b/www/apps/api-reference/next.config.mjs index c682e233c4646..89b345aaa70da 100644 --- a/www/apps/api-reference/next.config.mjs +++ b/www/apps/api-reference/next.config.mjs @@ -1,5 +1,7 @@ import mdx from "@next/mdx" import bundleAnalyzer from "@next/bundle-analyzer" +import rehypeMdxCodeProps from "rehype-mdx-code-props" +import rehypeSlug from "rehype-slug" /** @type {import('next').NextConfig} */ const nextConfig = { @@ -15,7 +17,15 @@ const nextConfig = { const withMDX = mdx({ extension: /\.mdx?$/, options: { - rehypePlugins: [], + rehypePlugins: [ + [ + rehypeMdxCodeProps, + { + tagName: "code", + }, + ], + [rehypeSlug], + ], development: process.env.NODE_ENV === "development", }, }) diff --git a/www/apps/api-reference/package.json b/www/apps/api-reference/package.json index 18e0a9cd481b3..1d6b2d3c9268a 100644 --- a/www/apps/api-reference/package.json +++ b/www/apps/api-reference/package.json @@ -45,6 +45,8 @@ "react-intersection-observer": "^9.5.3", "react-tooltip": "^5.19.0", "react-transition-group": "^4.4.5", + "rehype-mdx-code-props": "^2.0.0", + "rehype-slug": "^6.0.0", "slugify": "^1.6.6", "swr": "^2.2.0", "tailwind": "*", diff --git a/www/packages/docs-ui/src/components/Heading/H1/index.tsx b/www/packages/docs-ui/src/components/Heading/H1/index.tsx new file mode 100644 index 0000000000000..f9e0d42df07a0 --- /dev/null +++ b/www/packages/docs-ui/src/components/Heading/H1/index.tsx @@ -0,0 +1,19 @@ +import clsx from "clsx" +import React from "react" + +type H1Props = React.HTMLAttributes & { + id?: string +} + +export const H1 = ({ className, ...props }: H1Props) => { + return ( +

+ ) +} diff --git a/www/packages/docs-ui/src/components/Heading/H2/index.tsx b/www/packages/docs-ui/src/components/Heading/H2/index.tsx new file mode 100644 index 0000000000000..48eda599ef6c5 --- /dev/null +++ b/www/packages/docs-ui/src/components/Heading/H2/index.tsx @@ -0,0 +1,32 @@ +import clsx from "clsx" +import React from "react" +import { Link } from "@/components" + +type H2Props = React.HTMLAttributes & { + id?: string + passRef?: React.RefObject +} + +export const H2 = ({ className, children, passRef, ...props }: H2Props) => { + return ( +

+ {children} + {props.id && ( + + # + + )} +

+ ) +} diff --git a/www/packages/docs-ui/src/components/Heading/H3/index.tsx b/www/packages/docs-ui/src/components/Heading/H3/index.tsx new file mode 100644 index 0000000000000..5e2c3ba7514b4 --- /dev/null +++ b/www/packages/docs-ui/src/components/Heading/H3/index.tsx @@ -0,0 +1,30 @@ +import clsx from "clsx" +import React from "react" +import { Link } from "@/components" + +type H3Props = React.HTMLAttributes & { + id?: string +} + +export const H3 = ({ className, children, ...props }: H3Props) => { + return ( +

+ {children} + {props.id && ( + + # + + )} +

+ ) +} diff --git a/www/packages/docs-ui/src/components/Heading/H4/index.tsx b/www/packages/docs-ui/src/components/Heading/H4/index.tsx new file mode 100644 index 0000000000000..68d104df37d04 --- /dev/null +++ b/www/packages/docs-ui/src/components/Heading/H4/index.tsx @@ -0,0 +1,14 @@ +import clsx from "clsx" +import React from "react" + +export const H4 = ({ + className, + ...props +}: React.HTMLAttributes) => { + return ( +

+ ) +} diff --git a/www/packages/docs-ui/src/components/Heading/index.tsx b/www/packages/docs-ui/src/components/Heading/index.tsx new file mode 100644 index 0000000000000..b0bf275522def --- /dev/null +++ b/www/packages/docs-ui/src/components/Heading/index.tsx @@ -0,0 +1,4 @@ +export * from "./H1" +export * from "./H2" +export * from "./H3" +export * from "./H4" diff --git a/www/packages/docs-ui/src/components/MDXComponents/index.tsx b/www/packages/docs-ui/src/components/MDXComponents/index.tsx index 3cbb25321658d..39f2b75c1bf3d 100644 --- a/www/packages/docs-ui/src/components/MDXComponents/index.tsx +++ b/www/packages/docs-ui/src/components/MDXComponents/index.tsx @@ -10,7 +10,10 @@ import { DetailsSummary, DetailsProps, ZoomImg, - Link, + H1, + H2, + H3, + H4, } from "@/components" import clsx from "clsx" import { Text } from "@medusajs/ui" @@ -27,78 +30,10 @@ export const MDXComponents: MDXComponentsType = { Summary: DetailsSummary, Card, CardList, - h1: ({ className, ...props }: React.HTMLAttributes) => { - return ( -

- ) - }, - h2: ({ - className, - children, - ...props - }: React.HTMLAttributes) => { - return ( -

- {children} - {props.id && ( - - # - - )} -

- ) - }, - h3: ({ - className, - children, - ...props - }: React.HTMLAttributes) => { - return ( -

- {children} - {props.id && ( - - # - - )} -

- ) - }, - h4: ({ className, ...props }: React.HTMLAttributes) => { - return ( -

- ) - }, + h1: H1, + h2: H2, + h3: H3, + h4: H4, p: ({ className, ...props }: React.HTMLAttributes) => { return (

{ + return !item.loaded || (item.showLoadingIfEmpty && !item.children?.length) + }, [item]) useEffect(() => { - if (open && !item.loaded) { + if (open && itemShowLoading) { setShowLoading(true) } - }, [open]) + }, [open, itemShowLoading]) useEffect(() => { - if (item.loaded && showLoading) { + if (!itemShowLoading && showLoading) { setShowLoading(false) } - }, [item]) + }, [itemShowLoading, showLoading]) useEffect(() => { const isActive = isChildrenActive(item) diff --git a/www/packages/docs-ui/src/components/index.ts b/www/packages/docs-ui/src/components/index.ts index 824c7d400a46f..1843422e79ffb 100644 --- a/www/packages/docs-ui/src/components/index.ts +++ b/www/packages/docs-ui/src/components/index.ts @@ -24,6 +24,7 @@ export * from "./ExpandableNotice" export * from "./FeatureFlagNotice" export * from "./Feedback" export * from "./Feedback/Solutions" +export * from "./Heading" export * from "./HooksLoader" export * from "./Icons" export * from "./InlineIcon" diff --git a/www/packages/docs-ui/src/hooks/use-active-on-scroll/index.tsx b/www/packages/docs-ui/src/hooks/use-active-on-scroll/index.tsx index f71ea7a8b8254..61de751c5757d 100644 --- a/www/packages/docs-ui/src/hooks/use-active-on-scroll/index.tsx +++ b/www/packages/docs-ui/src/hooks/use-active-on-scroll/index.tsx @@ -14,12 +14,14 @@ export type UseActiveOnScrollProps = { rootElm?: Document | HTMLElement enable?: boolean useDefaultIfNoActive?: boolean + maxLevel?: number } export const useActiveOnScroll = ({ rootElm, enable = true, useDefaultIfNoActive = true, + maxLevel = 3, }: UseActiveOnScrollProps) => { const [items, setItems] = useState([]) const [activeItemId, setActiveItemId] = useState("") @@ -40,12 +42,23 @@ export const useActiveOnScroll = ({ return document }, [rootElm, isBrowser, enable]) + const querySelector = useMemo(() => { + let selector = "" + for (let i = 2; i <= maxLevel; i++) { + if (i > 2) { + selector += `,` + } + selector += `h${i}` + } + + return selector + }, [maxLevel]) const getHeadingsInElm = useCallback(() => { if (!isBrowser || !enable) { return [] } - return root?.querySelectorAll("h2,h3") + return root?.querySelectorAll(querySelector) }, [isBrowser, pathname, root, enable]) const setHeadingItems = useCallback(() => { if (!enable) { diff --git a/www/packages/docs-ui/src/layouts/main-content.tsx b/www/packages/docs-ui/src/layouts/main-content.tsx index 79f3abeb2831f..42c770856d84f 100644 --- a/www/packages/docs-ui/src/layouts/main-content.tsx +++ b/www/packages/docs-ui/src/layouts/main-content.tsx @@ -7,6 +7,7 @@ import { Bannerv2, MainNav, useIsBrowser } from ".." export type MainContentLayoutProps = { mainWrapperClasses?: string + contentClassName?: string showBanner?: boolean children: React.ReactNode } @@ -15,6 +16,7 @@ export const MainContentLayout = ({ children, mainWrapperClasses, showBanner = true, + contentClassName, }: MainContentLayoutProps) => { const { isBrowser } = useIsBrowser() const { desktopSidebarOpen } = useSidebar() @@ -57,7 +59,8 @@ export const MainContentLayout = ({

{children} diff --git a/www/packages/docs-ui/src/layouts/wide.tsx b/www/packages/docs-ui/src/layouts/wide.tsx index 02340b9613fc7..8c442946eeef8 100644 --- a/www/packages/docs-ui/src/layouts/wide.tsx +++ b/www/packages/docs-ui/src/layouts/wide.tsx @@ -14,6 +14,7 @@ export const WideLayout = ({
void initialOpen?: boolean + showLoadingIfEmpty?: boolean } export type SidebarItemSubCategory = SidebarItemCommon & { diff --git a/www/yarn.lock b/www/yarn.lock index 780625fa56950..836b0527fe01b 100644 --- a/www/yarn.lock +++ b/www/yarn.lock @@ -5582,6 +5582,8 @@ __metadata: react-intersection-observer: ^9.5.3 react-tooltip: ^5.19.0 react-transition-group: ^4.4.5 + rehype-mdx-code-props: ^2.0.0 + rehype-slug: ^6.0.0 slugify: ^1.6.6 swr: ^2.2.0 tailwind: "*"