docs: update to next 15 + eslint 9 (#9839)
* update next * updated react * update eslint * finish updating eslint * fix content lint errors * fix docs test * fix vale action * fix installation errors
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,862 @@
|
||||
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"
|
||||
|
||||
<Section checkActiveOnScroll>
|
||||
|
||||
<SectionContainer noTopPadding={true}>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
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.
|
||||
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
extraData={{
|
||||
area: "store",
|
||||
section: "introduction"
|
||||
}}
|
||||
reportLink={formatReportLink("store", "Introduction")}
|
||||
pathName="/api/store"
|
||||
question="Was this section helpful?"
|
||||
vertical={true}
|
||||
/>
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
<ClientLibraries />
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
</SectionContainer>
|
||||
|
||||
<SectionContainer noTopPadding={true}>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
## Authentication
|
||||
|
||||
There are two ways to send authenticated requests to the Medusa application: Using a JWT token or using a Cookie Session ID.
|
||||
|
||||
### 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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
#### How to Obtain the JWT Token
|
||||
|
||||
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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Obtain JWT token"
|
||||
curl -X POST '{backend_url}/auth/customer/emailpass' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"email": "user@example.com",
|
||||
"password": "supersecret"
|
||||
}'
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
If authenticated successfully, an object is returned in the response with the property `token` being the JWT token.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```json title="Example response"
|
||||
{
|
||||
"token": "123..."
|
||||
}
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
#### How to Use the JWT Token
|
||||
|
||||
To use the JWT token, pass it in the authorization bearer header.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Use JWT token"
|
||||
Authorization: Bearer {jwt_token}
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### 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.
|
||||
|
||||
### 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. */}
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
Then, send a request to the session authentication API route.
|
||||
|
||||
To view the cookie session ID, pass the `-v` option to the `curl` command.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Obtain cookie session"
|
||||
curl -v -X POST '{backend_url}/auth/session' \
|
||||
--header 'Authorization: Bearer {jwt_token}'
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
The headers will be logged in the terminal as well as the response. You
|
||||
should find in the headers a Cookie header.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Logged cookie session"
|
||||
Set-Cookie: connect.sid=s%3A2Bu8B...;
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
#### 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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```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.
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
#### 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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```js title="Include credentials in fetch"
|
||||
fetch(`<BACKEND_URL>/store/products`, {
|
||||
credentials: "include",
|
||||
})
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
extraData={{
|
||||
area: "store",
|
||||
section: "authentication-cookie"
|
||||
}}
|
||||
reportLink={formatReportLink("store", "Authentication - Cookie Session ID")}
|
||||
pathName="/api/store"
|
||||
question="Was this section helpful?"
|
||||
vertical={true}
|
||||
/>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
</SectionContainer>
|
||||
|
||||
<SectionContainer noTopPadding={true}>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
## Publishable API Key
|
||||
|
||||
You must pass a publishable API key in the header of your requests to the store API routes.
|
||||
|
||||
Publishable API Keys sets the scope of your request to one or more sales channels. This ensures you only
|
||||
retrieve products available in the publishable API key's sales channels, retrieve correct inventory details,
|
||||
and associate placed orders with the specified sales channel.
|
||||
|
||||
### How to Create a Publishable API Key
|
||||
|
||||
{/* TODO add v2 links */}
|
||||
|
||||
Create a publishable API key either using the [admin REST APIs](https://docs.medusajs.com/api/admin#api-keys_postapikeys), or using the Medusa Admin.
|
||||
|
||||
### How to Use a Publishable API Key
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
You pass the publishable API key in the header `x-publishable-api-key` in all your requests to the store APIs.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```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.
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
extraData={{
|
||||
area: "store",
|
||||
section: "publishable-api-key"
|
||||
}}
|
||||
reportLink={formatReportLink("store", "Publishable API Key")}
|
||||
pathName="/api/store"
|
||||
question="Was this section helpful?"
|
||||
vertical={true}
|
||||
/>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
</SectionContainer>
|
||||
|
||||
<SectionContainer noTopPadding={true}>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
## HTTP Compression
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Enable HTTP compression"
|
||||
x-no-compression: true
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
extraData={{
|
||||
area: "store",
|
||||
section: "http-compression"
|
||||
}}
|
||||
reportLink={formatReportLink("store", "HTTP Compression")}
|
||||
pathName="/api/store"
|
||||
question="Was this section helpful?"
|
||||
vertical={true}
|
||||
/>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
</SectionContainer>
|
||||
|
||||
<SectionContainer noTopPadding={true}>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
## Select Fields and Relations
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
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 `,`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Select fields"
|
||||
curl 'localhost:9000/store/products?fields=title,handle'
|
||||
```
|
||||
|
||||
This returns only the `title` and `handle` fields of a product.
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### Fields Operator
|
||||
|
||||
By default, only the selected fields and relations are returned in the response.
|
||||
|
||||
Before every field or relation, you can pass one of the following operators to change the default behavior:
|
||||
|
||||
- `+`: 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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing codeContentClassName="mt-3">
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### Select Relations
|
||||
|
||||
To select a relation, pass to `fields` the relation name prefixed by `*`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Select relations"
|
||||
curl 'localhost:9000/store/products?fields=*variants'
|
||||
```
|
||||
|
||||
This returns the variants of each product.
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### Select Fields in a Relation
|
||||
|
||||
The `*` prefix selects all fields of the relation's data model.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
To select a specific field, pass a `.<field>` suffix instead of the `*` prefix. For example, `variants.title`.
|
||||
|
||||
To specify multiple fields, pass each of the fields with the `<relation>.<field>` format, separated by a comma.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```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.
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
extraData={{
|
||||
area: "store",
|
||||
section: "select-fields"
|
||||
}}
|
||||
reportLink={formatReportLink("store", "Selecting Fields")}
|
||||
pathName="/api/store"
|
||||
question="Was this section helpful?"
|
||||
vertical={true}
|
||||
/>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
</SectionContainer>
|
||||
|
||||
<SectionContainer noTopPadding={true}>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
## 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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing codeContentClassName="mt-3">
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### Strings
|
||||
|
||||
|
||||
You can pass a string value in the form of `<parameter_name>=<value>`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="String filter"
|
||||
curl "http://localhost:9000/store/products?title=Shirt"
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
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`.
|
||||
|
||||
You can use tools like [this one](https://www.urlencoder.org/) to learn how
|
||||
a value can be encoded.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Encoded string filter"
|
||||
curl "http://localhost:9000/store/products?title=Blue%20Shirt"
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing codeContentClassName="mt-3">
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### Integers
|
||||
|
||||
You can pass an integer value in the form of `<parameter_name>=<value>`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Integer filter"
|
||||
curl "http://localhost:9000/store/products?offset=1"
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing codeContentClassName="mt-3">
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### Boolean
|
||||
|
||||
|
||||
You can pass a boolean value in the form of `<parameter_name>=<value>`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Boolean filter"
|
||||
curl "http://localhost:9000/store/products?is_giftcard=true"
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing codeContentClassName="mt-3">
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### 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`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Date filter"
|
||||
curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17"
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
You can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please
|
||||
note that the `T` and `Z` here are fixed.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Date and time filter"
|
||||
curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17T07:22:30Z"
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing codeContentClassName="mt-3">
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### 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>`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```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).
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing codeContentClassName="mt-3">
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### Object
|
||||
|
||||
|
||||
Object parameters must be passed as separate query parameters in the form
|
||||
`<parameter_name>[<key>]=<value>`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Object filter"
|
||||
curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17&created_at[$gt]=2022-09-17"
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
extraData={{
|
||||
area: "store",
|
||||
section: "query-parameters"
|
||||
}}
|
||||
reportLink={formatReportLink("store", "Query Parameter Types")}
|
||||
pathName="/api/store"
|
||||
question="Was this section helpful?"
|
||||
vertical={true}
|
||||
/>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
</SectionContainer>
|
||||
|
||||
<SectionContainer noTopPadding={true}>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
## Pagination
|
||||
|
||||
|
||||
### Query Parameters
|
||||
|
||||
|
||||
In listing API Routes, such as list products, you can control the pagination using the query parameters `limit` and `offset`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
`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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```bash title="Pagination query parameters"
|
||||
curl "http://localhost:9000/store/products?limit=5&offset=0"
|
||||
```
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### 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`.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing codeContentClassName="mt-3">
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
### 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.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```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.
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout addYSpacing>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
By default, the sort direction is ascending. To change it to
|
||||
descending, pass a dash (`-`) before the field name.
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
<DividedMarkdownCode>
|
||||
|
||||
```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.
|
||||
|
||||
</DividedMarkdownCode>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
extraData={{
|
||||
area: "store",
|
||||
section: "pagination"
|
||||
}}
|
||||
reportLink={formatReportLink("store", "Pagination")}
|
||||
pathName="/api/store"
|
||||
question="Was this section helpful?"
|
||||
vertical={true}
|
||||
/>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownLayout>
|
||||
|
||||
<DividedMarkdownContent>
|
||||
|
||||
## 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/customization/extend-models/extend-create-product) to find an example of extending an API route.
|
||||
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
extraData={{
|
||||
area: "admin",
|
||||
section: "workflows"
|
||||
}}
|
||||
reportLink={formatReportLink("admin", "Workflows")}
|
||||
pathName="/api/admin"
|
||||
question="Was this section helpful?"
|
||||
vertical={true}
|
||||
/>
|
||||
|
||||
</DividedMarkdownContent>
|
||||
|
||||
</DividedMarkdownLayout>
|
||||
|
||||
</SectionContainer>
|
||||
|
||||
</Section>
|
||||
Reference in New Issue
Block a user