869 lines
19 KiB
Plaintext
869 lines
19 KiB
Plaintext
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, H1 } from "docs-ui"
|
|
|
|
import ClientLibraries from "./client-libraries.mdx"
|
|
|
|
<Section checkActiveOnScroll>
|
|
|
|
<SectionContainer noTopPadding={true}>
|
|
|
|
<DividedMarkdownLayout>
|
|
|
|
<DividedMarkdownContent>
|
|
|
|
<H1 className={"!h2-docs scroll-m-[184px] lg:scroll-m-[264px]"} id="introduction">Medusa V2 Store API Reference</H1>
|
|
|
|
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"
|
|
}}
|
|
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"
|
|
}}
|
|
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"
|
|
}}
|
|
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"
|
|
}}
|
|
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"
|
|
}}
|
|
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
|
|
|
|
Array filters can be passed either as:
|
|
|
|
- `<parameter_name>[]=<value1>,<value2>`, separating the values by a comma.
|
|
- `<parameter_name>[]=<value1>&<parameter_name>[]=<value2>`, passing each value as a separate query parameter. You can also specify the index of each
|
|
parameter in the brackets `<parameter_name>[0]=<value>`.
|
|
|
|
</DividedMarkdownContent>
|
|
|
|
<DividedMarkdownCode>
|
|
|
|
<CodeTabs group="array-filter">
|
|
<CodeTab label="Comma-separated" value="comma-separated">
|
|
|
|
```bash
|
|
curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7,sc_234PGVB42PZ7N3YQEP2WDM7PC7"
|
|
```
|
|
|
|
</CodeTab>
|
|
<CodeTab label="Separate parameters" value="separate-query-parameters">
|
|
|
|
```bash
|
|
curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7"
|
|
```
|
|
|
|
</CodeTab>
|
|
</CodeTabs>
|
|
|
|
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"
|
|
}}
|
|
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"
|
|
}}
|
|
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](!docs!/learn/customization/extend-features/extend-create-product) to find an example of extending an API route.
|
|
|
|
<Feedback
|
|
event="survey_api-ref"
|
|
extraData={{
|
|
area: "admin",
|
|
section: "workflows"
|
|
}}
|
|
pathName="/api/admin"
|
|
question="Was this section helpful?"
|
|
vertical={true}
|
|
/>
|
|
|
|
</DividedMarkdownContent>
|
|
|
|
</DividedMarkdownLayout>
|
|
|
|
</SectionContainer>
|
|
|
|
</Section> |