asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: refactored versioning in api reference + modified v2 content (#7274)

Browse Source
This commit is contained in:
Shahed Nasser
2024-05-09 17:23:49 +03:00
committed by GitHub
parent 6da2964998
commit 5d0ffe8ff4
16 changed files with 1107 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
www/apps/api-reference/app/_mdx/admin.mdx → www/apps/api-reference/app/_mdx/v1/admin.mdx
View File

@@ -1,12 +1,9 @@
import { Feedback, CodeTabs, CodeTab } from "docs-ui"
import SectionContainer from "@/components/Section/Container"
import formatReportLink from "@/utils/format-report-link"
import VersionNote from "@/components/VersionNote"
<SectionContainer noTopPadding={true}>
<VersionNote />
This API reference includes Medusa's Admin APIs, which are REST APIs exposed by the Medusa backend. They are typically 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 backend URL.
@@ -135,17 +132,6 @@ You can also pass it to client libraries:
</CodeTab>
</CodeTabs>
<Feedback
event="survey_api-ref"
extraData={{
area: "admin",
section: "authentication-api-key"
}}
className="mb-3"
reportLink={formatReportLink("admin", "Authentication - API Token")}
pathName="/api/admin"
/>
### JWT Token
Use a JWT token to send authenticated requests. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications.

0
www/apps/api-reference/app/_mdx/client-libraries.mdx → www/apps/api-reference/app/_mdx/v1/client-libraries.mdx
View File

3
www/apps/api-reference/app/_mdx/store.mdx → www/apps/api-reference/app/_mdx/v1/store.mdx
View File

@@ -2,12 +2,9 @@
import { Feedback, CodeTabs, CodeTab } from "docs-ui"
import SectionContainer from "@/components/Section/Container"
import formatReportLink from "@/utils/format-report-link"
import VersionNote from "@/components/VersionNote"
<SectionContainer noTopPadding={true}>
<VersionNote />
This API reference includes Medusa's Store APIs, which are REST APIs exposed by the Medusa backend. They are typically 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 backend URL.

478
www/apps/api-reference/app/_mdx/v2/admin.mdx Normal file
View File

@@ -0,0 +1,478 @@
import { Feedback, CodeTabs, CodeTab } from "docs-ui"
import SectionContainer from "@/components/Section/Container"
import formatReportLink from "@/utils/format-report-link"
<SectionContainer noTopPadding={true}>
<Note type="warning" title="Production Warning">
Medusa v2.0 is in development and not suitable for production
environments. As such, the API reference is incomplete and subject to
change, so please use it with caution.
</Note>
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.
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.
<Feedback
event="survey_api-ref"
extraData={{
area: "admin",
section: "introduction"
}}
reportLink={formatReportLink("admin", "Introduction")}
pathName="/api/admin"
/>
</SectionContainer>
<SectionContainer noTopPadding={true}>
## Authentication
There are three ways to send authenticated requests to the Medusa server: Using an admin user's API token, using a JWT token in a bearer authorization header, or using a cookie session ID.
### 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
{/* TODO add correct link to auth route */}
JWT tokens are obtained by sending a request to the authentication route passing it the user's email and password in the request body.
For example:
```bash
curl -X POST '{backend_url}/auth/admin/emailpass' \
-H 'Content-Type: application/json' \
--data-raw '{
"email": "user@example.com",
"password": "supersecret"
}'
```
If authenticated successfully, an object is returned in the response with the property `token` being the JWT token.
#### How to Use the JWT Token
Pass the JWT token in the authorization bearer header:
```bash
Authorization: Bearer {jwt_token}
```
---
### API Token
Use a user's API Token to send authenticated requests.
<Note>
This authentication method relies on using another authentication method first, as you must be an authenticated user to create an API token.
</Note>
#### How to Create an API Token for a User
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}' \
--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:
```bash
Authorization: Basic {api_key_token}
```
---
### 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.
### How to Obtain the Cookie Session
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
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:
```bash
Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;
```
#### 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:
```bash
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:
```js
fetch(`<BACKEND_URL>/admin/products`, {
credentials: "include",
})
```
<Feedback
event="survey_api-ref"
extraData={{
area: "admin",
section: "authentication-cookie"
}}
reportLink={formatReportLink("admin", "Authentication - Cookie Session ID")}
pathName="/api/admin"
/>
</SectionContainer>
<SectionContainer noTopPadding={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:
```bash
x-no-compression: true
```
<Feedback
event="survey_api-ref"
extraData={{
area: "admin",
section: "http-compression"
}}
reportLink={formatReportLink("admin", "Authentication - Cookie Session ID")}
pathName="/api/admin"
/>
</SectionContainer>
<SectionContainer noTopPadding={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.
<Note type="warning">
When you pass the `fields` query, only specified fields and relations, along with the `id`, are retrieved in the result.
</Note>
### Select Multiple Fields
Separate the fields and relations you want to select with a comma.
For example:
```bash
curl 'localhost:9000/admin/products?fields=title,handle' \
-H 'Authorization: Bearer {jwt_token}'
```
This returns only the `title` and `handle` fields of a product.
### Select Relations
To select a relation, pass to `fields` the relation name prefixed by `.*`. For example:
```bash
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 `.*` suffix selects all fields of the relation's data model.
To select a specific field, change the `*` to the field's name.
To specify multiple fields, pass each of the fields with the `<relation>.<field>` format, separated by a comma.
For example:
```bash
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.
</SectionContainer>
<SectionContainer noTopPadding={true}>
## Query Parameter Types
This section covers how to pass some common data types as query parameters.
### Strings
You can pass a string value in the form of `<parameter_name>=<value>`.
For example:
```bash
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`:
```bash
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
You can pass an integer value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/admin/products?offset=1" \
-H 'Authorization: Bearer {jwt_token}'
```
### Boolean
You can pass a boolean value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/admin/products?is_giftcard=true" \
-H 'Authorization: Bearer {jwt_token}'
```
### Date and DateTime
You can pass a date value in the form `<parameter_name>=<value>`. The date
must be in the format `YYYY-MM-DD`.
For example:
```bash
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
curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17T07:22:30Z" \
-H 'Authorization: Bearer {jwt_token}'
```
### Array
Each array value must be passed as a separate query parameter in the form
`<parameter_name>[]=<value>`. You can also specify the index of each
parameter in the brackets `<parameter_name>[0]=<value>`.
For example:
```bash
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
Object parameters must be passed as separate query parameters in the form
`<parameter_name>[<key>]=<value>`.
For example:
```bash
curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17" \
-H 'Authorization: Bearer {jwt_token}'
```
<Feedback
event="survey_api-ref"
extraData={{
area: "admin",
section: "query-parameters"
}}
reportLink={formatReportLink("admin", "Query Parameter Types")}
pathName="/api/admin"
/>
</SectionContainer>
<SectionContainer noTopPadding={true}>
## Pagination
### Query Parameters
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
curl "http://localhost:9000/admin/products?limit=5" \
-H 'Authorization: Bearer {jwt_token}'
```
### Response Fields
In the response of listing API Routes, aside from the records retrieved,
there are three pagination-related fields returned:
- `limit`: the maximum number of items that can be returned in the response.
- `offset`: the number of items that were skipped before the records in the result.
- `count`: the total number of available items of this data model. It can be used to determine how many pages are there.
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
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
curl "http://localhost:9000/admin/products?order=created_at" \
-H 'Authorization: Bearer {jwt_token}'
```
By default, the sort direction is ascending. To change it to
descending, pass a dash (`-`) before the field name.
For example:
```bash
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.
<Feedback
event="survey_api-ref"
extraData={{
area: "admin",
section: "pagination"
}}
reportLink={formatReportLink("admin", "Pagination")}
pathName="/api/admin"
/>
</SectionContainer>

20
www/apps/api-reference/app/_mdx/v2/client-libraries.mdx Normal file
View File

@@ -0,0 +1,20 @@
import Space from "@/components/Space"
import DownloadFull from "@/components/DownloadFull"
### Just Getting Started?
Check out the [quickstart guide](https://docs.medusajs.com/create-medusa-app).
<Space bottom={8} />
<Note type="soon">
Support for v2 API Routes is coming soon in Medusa JS Client and Medusa React.
</Note>
### 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.
<DownloadFull />

495
www/apps/api-reference/app/_mdx/v2/store.mdx Normal file
View File

@@ -0,0 +1,495 @@
import { Feedback, CodeTabs, CodeTab } from "docs-ui"
import SectionContainer from "@/components/Section/Container"
import formatReportLink from "@/utils/format-report-link"
<SectionContainer noTopPadding={true}>
<Note type="warning" title="Production Warning">
Medusa v2.0 is in development and not suitable for production
environments. As such, the API reference is incomplete and subject to
change, so please use it with caution.
</Note>
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.
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.
<Feedback
event="survey_api-ref"
extraData={{
area: "store",
section: "introduction"
}}
reportLink={formatReportLink("store", "Introduction")}
pathName="/api/store"
/>
</SectionContainer>
<SectionContainer noTopPadding={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
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
{/* TODO add correct link to auth route */}
JWT tokens are obtained by sending a request to the authentication route passing it the customer's email and password in the request body.
For example:
```bash
curl -X POST '{backend_url}/auth/store/emailpass' \
-H 'Content-Type: application/json' \
--data-raw '{
"email": "user@example.com",
"password": "supersecret"
}'
```
<Note>
{/* TODO add link to implementing login with google guide. */}
Alternatively, you can use the `google` provider instead of `emailpass`.
</Note>
If authenticated successfully, an object is returned in the response with the property `token` being the JWT token.
#### How to Use the JWT Token
Pass the JWT token in the authorization bearer header:
```bash
Authorization: Bearer {jwt_token}
```
---
### 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.
### How to Obtain the Cookie Session
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
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:
```bash
Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;
```
#### 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:
```bash
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:
```js
fetch(`<BACKEND_URL>/store/products`, {
credentials: "include",
})
```
<Feedback
event="survey_api-ref"
extraData={{
area: "store",
section: "authentication-cookie"
}}
reportLink={formatReportLink("store", "Authentication - Cookie Session ID")}
pathName="/api/store"
/>
</SectionContainer>
<SectionContainer noTopPadding={true}>
## Publishable API Key
Publishable API Keys allow you to send a request with a pre-defined scope. You can associate the
publishable API key with one or more resources, such as sales channels, then include the publishable
API key in the header of your requests.
The Medusa application will infer the scope of the current
request based on the publishable API key. At the moment, publishable API keys only work with sales channels.
It's highly recommended to create a publishable API key and pass it in the header of all your requests to the
store APIs.
{/* TODO add link to the v2 guide */}
{/* You can learn more about publishable API keys and how to use them in [this documentation](https://docs.medusajs.com/development/publishable-api-keys/). */}
### How to Create a Publishable API Key
{/* TODO add v2 links */}
Create a publishable API key either using the admin REST APIs, or using the Medusa Admin.
### How to Use a Publishable API Key
You can pass the publishable API key in the header `x-publishable-api-key` in all your requests to the store APIs:
```bash
x-publishable-api-key: {your_publishable_api_key}
```
<Feedback
event="survey_api-ref"
extraData={{
area: "store",
section: "publishable-api-key"
}}
reportLink={formatReportLink("store", "Publishable API Key")}
pathName="/api/store"
/>
</SectionContainer>
<SectionContainer noTopPadding={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:
```bash
x-no-compression: true
```
<Feedback
event="survey_api-ref"
extraData={{
area: "store",
section: "http-compression"
}}
reportLink={formatReportLink("store", "HTTP Compression")}
pathName="/api/store"
/>
</SectionContainer>
<SectionContainer noTopPadding={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.
<Note type="warning">
When you pass the `fields` query, only specified fields and relations, along with the `id`, are retrieved in the result.
</Note>
### Select Multiple Fields
Separate the fields and relations you want to select with a comma.
For example:
```bash
curl 'localhost:9000/store/products?fields=title,handle' \
-H 'Authorization: Bearer {jwt_token}'
```
This returns only the `title` and `handle` fields of a product.
### Select Relations
To select a relation, pass to `fields` the relation name prefixed by `.*`. For example:
```bash
curl 'localhost:9000/store/products?fields=variants.*' \
-H 'Authorization: Bearer {jwt_token}'
```
This returns the variants of each product.
### Select Fields in a Relation
The `.*` suffix selects all fields of the relation's data model.
To select a specific field, change the `*` to the field's name.
To specify multiple fields, pass each of the fields with the `<relation>.<field>` format, separated by a comma.
For example:
```bash
curl 'localhost:9000/store/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.
<Feedback
event="survey_api-ref"
extraData={{
area: "store",
section: "select-fields"
}}
reportLink={formatReportLink("store", "Selecting Fields")}
pathName="/api/store"
/>
</SectionContainer>
<SectionContainer noTopPadding={true}>
## 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.
### Strings
You can pass a string value in the form of `<parameter_name>=<value>`.
For example:
```bash
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`:
```bash
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 `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/store/products?offset=1"
```
### Boolean
You can pass a boolean value in the form of `<parameter_name>=<value>`.
For example:
```bash
curl "http://localhost:9000/store/products?is_giftcard=true"
```
### Date and DateTime
You can pass a date value in the form `<parameter_name>=<value>`. The date
must be in the format `YYYY-MM-DD`.
For example:
```bash
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
curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z"
```
### Array
Each array value must be passed as a separate query parameter in the form
`<parameter_name>[]=<value>`. You can also specify the index of each
parameter in the brackets `<parameter_name>[0]=<value>`.
For example:
```bash
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
Object parameters must be passed as separate query parameters in the form
`<parameter_name>[<key>]=<value>`.
For example:
```bash
curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17"
```
<Feedback
event="survey_api-ref"
extraData={{
area: "store",
section: "query-parameters"
}}
reportLink={formatReportLink("store", "Query Parameter Types")}
pathName="/api/store"
/>
</SectionContainer>
<SectionContainer noTopPadding={true}>
## Pagination
### Query Parameters
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" \
-H 'Authorization: Bearer {jwt_token}'
```
### Response Fields
In the response of listing API Routes, aside from the records retrieved,
there are three pagination-related fields returned:
- `limit`: the maximum number of items that can be returned in the response.
- `offset`: the number of items that were skipped before the records in the result.
- `count`: the total number of available items of this data model. It can be used to determine how many pages are there.
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
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
curl "http://localhost:9000/store/products?order=created_at" \
-H 'Authorization: Bearer {jwt_token}'
```
By default, the sort direction is ascending. To change it to
descending, pass a dash (`-`) before the field name.
For example:
```bash
curl "http://localhost:9000/store/products?order=-created_at" \
-H 'Authorization: Bearer {jwt_token}'
```
This sorts the products by their `created_at` field in the descending order.
<Feedback
event="survey_api-ref"
extraData={{
area: "store",
section: "pagination"
}}
reportLink={formatReportLink("store", "Pagination")}
pathName="/api/store"
/>
</SectionContainer>

12
www/apps/api-reference/app/api/[area]/page.tsx
View File

@@ -1,7 +1,7 @@
import AreaProvider from "@/providers/area"
import AdminDescription from "../../_mdx/admin.mdx"
import StoreDescription from "../../_mdx/store.mdx"
import ClientLibraries from "../../_mdx/client-libraries.mdx"
import AdminContentV1 from "../../_mdx/v1/admin.mdx"
import StoreContentV1 from "../../_mdx/v1/store.mdx"
import ClientLibrariesV1 from "../../_mdx/v1/client-libraries.mdx"
import Section from "@/components/Section"
import Tags from "@/components/Tags"
import type { Area } from "@/types/openapi"
@@ -25,11 +25,11 @@ const ReferencePage = async ({ params: { area } }: ReferencePageProps) => {
mainContent={
<Section>
<PageHeading className="!text-h2 hidden lg:block" />
{area.includes("admin") && <AdminDescription />}
{area.includes("store") && <StoreDescription />}
{area.includes("admin") && <AdminContentV1 />}
{area.includes("store") && <StoreContentV1 />}
</Section>
}
codeContent={<ClientLibraries />}
codeContent={<ClientLibrariesV1 />}
className="flex-col-reverse"
/>
<Tags />

BIN
www/apps/api-reference/app/api/[area]/v2/opengraph-image.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 253 KiB

62
www/apps/api-reference/app/api/[area]/v2/page.tsx Normal file
View File

@@ -0,0 +1,62 @@
import AreaProvider from "@/providers/area"
import AdminContentV2 from "../../../_mdx/v2/admin.mdx"
import StoreContentV2 from "../../../_mdx/v2/store.mdx"
import ClientLibrariesV2 from "../../../_mdx/v2/client-libraries.mdx"
import Section from "@/components/Section"
import Tags from "@/components/Tags"
import type { Area } from "@/types/openapi"
import DividedLayout from "@/layouts/Divided"
import { capitalize } from "docs-ui"
import PageTitleProvider from "@/providers/page-title"
import PageHeading from "@/components/PageHeading"
type ReferencePageProps = {
params: {
area: Area
}
}
const ReferencePage = async ({ params: { area } }: ReferencePageProps) => {
return (
<AreaProvider area={area}>
<PageTitleProvider>
<PageHeading className="!text-h2 block lg:hidden" />
<DividedLayout
mainContent={
<Section>
<PageHeading className="!text-h2 hidden lg:block" />
{area.includes("admin") && <AdminContentV2 />}
{area.includes("store") && <StoreContentV2 />}
</Section>
}
codeContent={<ClientLibrariesV2 />}
className="flex-col-reverse"
/>
<Tags />
</PageTitleProvider>
</AreaProvider>
)
}
export default ReferencePage
export function generateMetadata({ params: { area } }: ReferencePageProps) {
return {
title: `Medusa ${capitalize(area)} API Reference`,
description: `REST API reference for the Medusa ${area} API. This reference includes code snippets and examples for Medusa JS Client and cURL.`,
metadataBase: process.env.NEXT_PUBLIC_BASE_URL,
}
}
export const dynamicParams = false
export async function generateStaticParams() {
return [
{
area: "admin",
},
{
area: "store",
},
]
}

BIN
www/apps/api-reference/app/api/[area]/v2/twitter-image.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 253 KiB

6
www/apps/api-reference/components/Navbar/index.tsx
View File

@@ -11,11 +11,13 @@ import { useMemo } from "react"
import { config } from "../../config"
import { usePathname } from "next/navigation"
import VersionSwitcher from "../VersionSwitcher"
import { useVersion } from "../../providers/version"
const Navbar = () => {
const { setMobileSidebarOpen, mobileSidebarOpen } = useSidebar()
const pathname = usePathname()
const { isLoading } = usePageLoading()
const { isVersioningEnabled } = useVersion()
const navbarItems = useMemo(
() =>
@@ -38,9 +40,7 @@ const Navbar = () => {
mobileSidebarOpen,
}}
additionalActionsBefore={
<>
{process.env.NEXT_PUBLIC_VERSIONING === "true" && <VersionSwitcher />}
</>
<>{isVersioningEnabled && <VersionSwitcher />}</>
}
additionalActionsAfter={<FeedbackModal />}
isLoading={isLoading}

5
www/apps/api-reference/components/PageHeading/index.tsx
View File

@@ -10,10 +10,9 @@ type PageHeadingProps = {
const PageHeading = ({ className }: PageHeadingProps) => {
const { area } = useArea()
const { version } = useVersion()
const { version, isVersioningEnabled } = useVersion()
const versionText =
process.env.NEXT_PUBLIC_VERSIONING === "true" ? ` V${version}` : ""
const versionText = isVersioningEnabled ? ` V${version}` : ""
return (
<h1 className={className}>

22
www/apps/api-reference/components/VersionNote/index.tsx
View File

@@ -1,22 +0,0 @@
"use client"
import { Note } from "docs-ui"
import { useVersion } from "../../providers/version"
const VersionNote = () => {
const { version } = useVersion()
return (
<>
{version === "2" && (
<Note type="warning" title="Production Warning">
Medusa v2.0 is in development and not suitable for production
environments. As such, the API reference is incomplete and subject to
change, so please use it with caution.
</Note>
)}
</>
)
}
export default VersionNote

15
www/apps/api-reference/components/VersionSwitcher/index.tsx
View File

@@ -1,11 +1,13 @@
"use client"
import { Toggle } from "docs-ui"
import { useVersion } from "../../providers/version"
import clsx from "clsx"
import { usePathname } from "next/navigation"
import { useVersion } from "../../providers/version"
const VersionSwitcher = () => {
const { version, changeVersion } = useVersion()
const pathname = usePathname()
const { version } = useVersion()
return (
<div className="flex gap-0.5 justify-center items-center">
@@ -19,7 +21,14 @@ const VersionSwitcher = () => {
</span>
<Toggle
checked={version === "2"}
onCheckedChange={(checked) => changeVersion(checked ? "2" : "1")}
onCheckedChange={(checked) => {
let newPath = pathname.replace("/v2", "")
if (checked) {
newPath += `/v2`
}
location.href = location.href.replace(pathname, newPath)
}}
/>
<span
className={clsx(

18
www/apps/api-reference/middleware.ts Normal file
View File

@@ -0,0 +1,18 @@
import { NextResponse } from "next/server"
import type { NextRequest } from "next/server"
export function middleware(request: NextRequest) {
if (
process.env.NEXT_PUBLIC_VERSIONING !== "true" &&
request.url.includes("/v2")
) {
const url = new URL(request.url)
return NextResponse.redirect(
new URL(url.pathname.replace("/v2", ""), request.url)
)
}
}
export const config = {
matcher: "/api/:path*",
}

49
www/apps/api-reference/providers/version.tsx
View File

@@ -1,13 +1,12 @@
"use client"
import { createContext, useContext, useEffect, useState } from "react"
import { createContext, useContext, useMemo } from "react"
import { Version } from "../types/openapi"
import { usePathname } from "next/navigation"
import { useIsBrowser } from "docs-ui"
type VersionContextType = {
version: Version
changeVersion: (value: Version) => void
isVersioningEnabled: boolean
}
const VersionContext = createContext<VersionContextType | null>(null)
@@ -18,44 +17,18 @@ type VersionProviderProps = {
const VersionProvider = ({ children }: VersionProviderProps) => {
const pathname = usePathname()
const [version, setVersion] = useState<Version>("1")
const isBrowser = useIsBrowser()
const changeVersion = (version: Version) => {
if (!isBrowser || process.env.NEXT_PUBLIC_VERSIONING !== "true") {
return
}
localStorage.setItem("api-version", version)
location.href = `${location.href.substring(
0,
location.href.indexOf(location.pathname)
)}${pathname}`
}
useEffect(() => {
if (!isBrowser || process.env.NEXT_PUBLIC_VERSIONING !== "true") {
return
}
// try to load from localstorage
const versionInLocalStorage = localStorage.getItem("api-version") as Version
if (versionInLocalStorage) {
setVersion(versionInLocalStorage)
}
}, [isBrowser])
useEffect(() => {
if (!isBrowser || process.env.NEXT_PUBLIC_VERSIONING !== "true") {
return
}
const versionInLocalStorage = localStorage.getItem("api-version") as Version
if (version !== versionInLocalStorage) {
localStorage.setItem("api-version", version)
}
}, [version, isBrowser])
const version = useMemo(() => {
return pathname.includes("v2") ? "2" : "1"
}, [pathname])
return (
<VersionContext.Provider value={{ version, changeVersion }}>
<VersionContext.Provider
value={{
version,
isVersioningEnabled: process.env.NEXT_PUBLIC_VERSIONING === "true",
}}
>
{children}
</VersionContext.Provider>
)