docs: update endpoints to use file-routing approach (#5397)
- Move the original guides for creating endpoints and middlewares to sub-sections in the Endpoints category. - Replace existing guides for endpoints and middlewares with the new approach. - Update all endpoints-related snippets across docs to use this new approach.
This commit is contained in:
Shahed Nasser
@@ -6,9 +6,9 @@ import formatReportLink from "@/utils/format-report-link"
|
||||
|
||||
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 endpoints are prefixed with `/admin`. So, during development, the endpoints will be available under the path `http://localhost:9000/admin`. For production, replace `http://localhost:9000` with your Medusa backend URL.
|
||||
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.
|
||||
|
||||
There are different ways you can send requests to these endpoints, including:
|
||||
There are different ways you can send requests to these API Routes, including:
|
||||
|
||||
- Using Medusa's [JavaScript Client](https://docs.medusajs.com/js-client/overview)
|
||||
- Using the [Medusa React](https://docs.medusajs.com/medusa-react/overview) library
|
||||
@@ -40,7 +40,7 @@ Use a user's API Token to send authenticated requests.
|
||||
|
||||
#### How to Add API Token to a User
|
||||
|
||||
You can use the Update User endpoint to add or update the user's API token:
|
||||
You can use the Update User API Route to add or update the user's API token:
|
||||
|
||||
<CodeTabs
|
||||
tabs={[
|
||||
@@ -158,7 +158,7 @@ Use a JWT token to send authenticated requests. Authentication state is managed
|
||||
|
||||
#### How to Obtain the JWT Token
|
||||
|
||||
JWT tokens are obtained by sending a request to the [User Login (JWT) endpoint](#auth_posttoken) passing it the user's email and password in the request body. For example:
|
||||
JWT tokens are obtained by sending a request to the [User Login (JWT) API Route](#auth_posttoken) passing it the user's email and password in the request body. For example:
|
||||
|
||||
```bash
|
||||
curl -X POST 'https://medusa-url.com/admin/auth/token' \
|
||||
@@ -331,8 +331,8 @@ const App = () => {
|
||||
|
||||
## Expanding Fields
|
||||
|
||||
In many endpoints you'll find an `expand` query parameter that can be passed
|
||||
to the endpoint. You can use the `expand` query parameter to unpack an
|
||||
In many API Routes you'll find an `expand` query parameter that can be passed
|
||||
to the API Route. You can use the `expand` query parameter to unpack an
|
||||
entity's relations and return them in the response.
|
||||
|
||||
|
||||
@@ -544,8 +544,8 @@ relations like `collection`.
|
||||
## Selecting Fields
|
||||
|
||||
|
||||
In many endpoints you'll find a `fields` query parameter that can be passed
|
||||
to the endpoint. You can use the `fields` query parameter to specify which
|
||||
In many API Routes you'll find a `fields` query parameter that can be passed
|
||||
to the API Route. You can use the `fields` query parameter to specify which
|
||||
fields in the entity should be returned in the response.
|
||||
|
||||
|
||||
@@ -876,7 +876,7 @@ export default Products`,
|
||||
|
||||
|
||||
This section covers how to pass some common data types as query parameters.
|
||||
This is useful if you're sending requests to the API endpoints and not using
|
||||
This is useful if you're sending requests to the API routes and not using
|
||||
the JS Client. For example, when using cURL or Postman.
|
||||
|
||||
|
||||
@@ -1028,7 +1028,7 @@ curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17&created_
|
||||
### Query Parameters
|
||||
|
||||
|
||||
In listing endpoints, such as list customers or list products, you can control the pagination using the query parameters `limit` and `offset`.
|
||||
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 that can be return in the response. `offset` is used to specify how many items to skip before returning the resulting entities.
|
||||
@@ -1037,7 +1037,7 @@ In listing endpoints, such as list customers or list products, you can control t
|
||||
You can 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, to limit the number of products returned in the List Products endpoint:
|
||||
For example, to limit the number of products returned in the List Products API Route:
|
||||
|
||||
<CodeTabs
|
||||
tabs={[
|
||||
@@ -1095,7 +1095,7 @@ export default Products`,
|
||||
### Response Fields
|
||||
|
||||
|
||||
In the response of listing endpoints, aside from the entities retrieved,
|
||||
In the response of listing API Routes, aside from the entities retrieved,
|
||||
there are three pagination-related fields returned: `count`, `limit`, and
|
||||
`offset`.
|
||||
|
||||
@@ -1116,7 +1116,7 @@ For example, if the `count` is 100 and the `limit` is 50, you can divide the
|
||||
### Sort Order
|
||||
|
||||
|
||||
The `order` field available on endpoints supporting pagination allows you to
|
||||
The `order` field available on API Routes supporting pagination allows you to
|
||||
sort the retrieved items by an attribute of that item. For example, you can
|
||||
sort products by their `created_at` attribute by setting `order` to
|
||||
`created_at`:
|
||||
|
||||
@@ -7,9 +7,9 @@ import formatReportLink from "@/utils/format-report-link"
|
||||
|
||||
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 endpoints are prefixed with `/store`. So, during development, the endpoints will be available under the path `http://localhost:9000/store`. For production, replace `http://localhost:9000` with your Medusa backend URL.
|
||||
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.
|
||||
|
||||
There are different ways you can send requests to these endpoints, including:
|
||||
There are different ways you can send requests to these API Routes, including:
|
||||
|
||||
- Using Medusa's [JavaScript Client](https://docs.medusajs.com/js-client/overview)
|
||||
- Using the [Medusa React](https://docs.medusajs.com/medusa-react/overview) library
|
||||
@@ -41,7 +41,7 @@ Use a JWT token to send authenticated requests. Authentication state is managed
|
||||
|
||||
#### How to Obtain the JWT Token
|
||||
|
||||
JWT tokens are obtained by sending a request to the [Customer Login (JWT) endpoint](#auth_authtoken) passing it the customer's email and password in the request body. For example:
|
||||
JWT tokens are obtained by sending a request to the [Customer Login (JWT) API Route](#auth_authtoken) passing it the customer's email and password in the request body. For example:
|
||||
|
||||
```bash
|
||||
curl -X POST 'https://medusa-url.com/store/auth/token' \
|
||||
@@ -297,8 +297,8 @@ const App = () => {
|
||||
## Expanding Fields
|
||||
|
||||
|
||||
In many endpoints you'll find an `expand` query parameter that can be passed
|
||||
to the endpoint. You can use the `expand` query parameter to unpack an
|
||||
In many API Routes you'll find an `expand` query parameter that can be passed
|
||||
to the API Route. You can use the `expand` query parameter to unpack an
|
||||
entity's relations and return them in the response.
|
||||
|
||||
|
||||
@@ -501,8 +501,8 @@ relations like `collection`.
|
||||
## Selecting Fields
|
||||
|
||||
|
||||
In many endpoints you'll find a `fields` query parameter that can be passed
|
||||
to the endpoint. You can use the `fields` query parameter to specify which
|
||||
In many API Routes you'll find a `fields` query parameter that can be passed
|
||||
to the API Route. You can use the `fields` query parameter to specify which
|
||||
fields in the entity should be returned in the response.
|
||||
|
||||
|
||||
@@ -823,7 +823,7 @@ export default Products`,
|
||||
|
||||
|
||||
This section covers how to pass some common data types as query parameters.
|
||||
This is useful if you're sending requests to the API endpoints and not using
|
||||
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.
|
||||
|
||||
|
||||
@@ -966,7 +966,7 @@ curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_
|
||||
### Query Parameters
|
||||
|
||||
|
||||
In listing endpoints, such as list customers or list products, you can
|
||||
In listing API Routes, such as list customers or list products, you can
|
||||
control the pagination using the query parameters `limit` and `offset`.
|
||||
|
||||
|
||||
@@ -981,7 +981,7 @@ offset should be `50`, and so on.
|
||||
|
||||
|
||||
For example, to limit the number of products returned in the List Products
|
||||
endpoint:
|
||||
API Route:
|
||||
|
||||
<CodeTabs
|
||||
tabs={[
|
||||
@@ -1037,7 +1037,7 @@ export default Products`,
|
||||
### Response Fields
|
||||
|
||||
|
||||
In the response of listing endpoints, aside from the entities retrieved,
|
||||
In the response of listing API Routes, aside from the entities retrieved,
|
||||
there are three pagination-related fields returned: `count`, `limit`, and
|
||||
`offset`.
|
||||
|
||||
@@ -1058,7 +1058,7 @@ For example, if the `count` is 100 and the `limit` is 50, you can divide the
|
||||
### Sort Order
|
||||
|
||||
|
||||
The `order` field available on endpoints supporting pagination allows you to
|
||||
The `order` field available on API Routes supporting pagination allows you to
|
||||
sort the retrieved items by an attribute of that item. For example, you can
|
||||
sort products by their `created_at` attribute by setting `order` to
|
||||
`created_at`:
|
||||
|
||||
@@ -72,7 +72,7 @@ const TagsOperationDescriptionSection = ({
|
||||
reportLink={formatReportLink(area, operation.summary)}
|
||||
className="!my-2"
|
||||
vertical={true}
|
||||
question="Did this endpoint run successfully?"
|
||||
question="Did this API Route run successfully?"
|
||||
/>
|
||||
{operation.externalDocs && (
|
||||
<>
|
||||
|
||||
@@ -33,7 +33,7 @@ const TagPaths = ({ tag, className }: TagPathsProps) => {
|
||||
const { loading } = useLoading()
|
||||
// if paths are already loaded since through
|
||||
// the expanded field, they're loaded directly
|
||||
// otherwise, they're loaded using the API endpoint
|
||||
// otherwise, they're loaded using the API route
|
||||
let paths: PathsObject =
|
||||
baseSpecs?.expandedTags &&
|
||||
Object.hasOwn(baseSpecs.expandedTags, tagSlugName)
|
||||
|
||||
@@ -13,11 +13,11 @@ tags:
|
||||
that, they can create an Oauth provider within the plugin that handles the
|
||||
authentication.
|
||||
|
||||
The Apps Oauth endpoints allows admins to manage and generate token for an
|
||||
The Apps Oauth API Routes allows admins to manage and generate token for an
|
||||
app using its oauth provider.
|
||||
- name: Auth
|
||||
description: >
|
||||
Authentication endpoints allow admin users to manage their session, such
|
||||
Authentication API Routes allow admin users to manage their session, such
|
||||
as login or log out.
|
||||
|
||||
When an admin user is logged in, the cookie header is set indicating the
|
||||
@@ -31,7 +31,7 @@ tags:
|
||||
asynchronusly. For example, the Import Product feature is implemented
|
||||
using batch jobs.
|
||||
|
||||
Batch Job endpoints allows admins to manage the batch jobs and their
|
||||
Batch Job API Routes allows admins to manage the batch jobs and their
|
||||
state.
|
||||
externalDocs:
|
||||
description: How to import products
|
||||
@@ -41,7 +41,7 @@ tags:
|
||||
A store can use unlimited currencies, and each region must be associated
|
||||
with at least one currency.
|
||||
|
||||
Currencies are defined within the Medusa backend. Currency endpoints allow
|
||||
Currencies are defined within the Medusa backend. Currency API Routes allow
|
||||
admins to list and update currencies.
|
||||
externalDocs:
|
||||
description: How to manage currencies
|
||||
@@ -69,7 +69,7 @@ tags:
|
||||
Admins can create discounts with conditions and rules, providing them with
|
||||
advanced settings for variety of cases.
|
||||
|
||||
The Discount endpoints can be used to manage discounts, their conditions,
|
||||
The Discount API Routes can be used to manage discounts, their conditions,
|
||||
resources, and more.
|
||||
externalDocs:
|
||||
description: How to manage discounts
|
||||
@@ -87,7 +87,7 @@ tags:
|
||||
specifying options like their balance, region, and more.
|
||||
|
||||
These gift cards are different than the saleable gift cards in a store,
|
||||
which are created and managed through Product endpoints.
|
||||
which are created and managed through Product API Routes.
|
||||
externalDocs:
|
||||
description: How to manage gift cards
|
||||
url: >-
|
||||
@@ -195,7 +195,7 @@ tags:
|
||||
Product variants are the actual salable item in your store. Each variant
|
||||
is a combination of the different option values available on the product.
|
||||
|
||||
Product variants can be managed through the Products endpoints.
|
||||
Product variants can be managed through the Products API Routes.
|
||||
externalDocs:
|
||||
description: How to manage product variants
|
||||
url: >-
|
||||
@@ -207,7 +207,7 @@ tags:
|
||||
|
||||
For example, a publishable API key can be associated with one or more
|
||||
sales channels. When it is passed in the header of a request to the List
|
||||
Product store endpoint,
|
||||
Product store API Route,
|
||||
|
||||
the sales channels are inferred from the key and only products associated
|
||||
with those sales channels are retrieved.
|
||||
@@ -330,7 +330,7 @@ tags:
|
||||
url: https://docs.medusajs.com/modules/taxes/admin/manage-tax-rates
|
||||
- name: Uploads
|
||||
description: >
|
||||
The upload endpoints are used to upload any type of resources. For
|
||||
The upload API Routes are used to upload any type of resources. For
|
||||
example, they can be used to upload CSV files that are used to import
|
||||
products into the store.
|
||||
externalDocs:
|
||||
|
||||
@@ -8,7 +8,7 @@ info:
|
||||
tags:
|
||||
- name: Auth
|
||||
description: >
|
||||
Authentication endpoints allow customers to manage their session, such as
|
||||
Authentication API Routes allow customers to manage their session, such as
|
||||
login or log out.
|
||||
|
||||
When a customer is logged in, the cookie header is set indicating the
|
||||
@@ -40,8 +40,8 @@ tags:
|
||||
Customers can use gift cards during checkout to deduct the gift card's
|
||||
balance from the checkout total.
|
||||
|
||||
The Gift Card endpoints allow retrieving a gift card's details by its
|
||||
code. A gift card can be applied to a cart using the Carts endpoints.
|
||||
The Gift Card API Routes allow retrieving a gift card's details by its
|
||||
code. A gift card can be applied to a cart using the Carts API Routes.
|
||||
externalDocs:
|
||||
description: How to use gift cards in a storefront
|
||||
url: https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards
|
||||
@@ -49,8 +49,8 @@ tags:
|
||||
description: >
|
||||
Orders are purchases made by customers, typically through a storefront.
|
||||
|
||||
Orders are placed and created using the Carts endpoints. The Orders
|
||||
endpoints allow retrieving and claiming orders.
|
||||
Orders are placed and created using the Carts API Routes. The Orders
|
||||
API Routes allow retrieving and claiming orders.
|
||||
externalDocs:
|
||||
description: How to retrieve order details in a storefront
|
||||
url: >-
|
||||
@@ -75,7 +75,7 @@ tags:
|
||||
cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards)
|
||||
in a store.
|
||||
|
||||
Using these endpoints, you can filter products by categories, collections,
|
||||
Using these API Routes, you can filter products by categories, collections,
|
||||
sales channels, and more.
|
||||
externalDocs:
|
||||
description: How to show products in a storefront
|
||||
@@ -89,7 +89,7 @@ tags:
|
||||
Products can be categoriezed into categories. A product can be associated
|
||||
more than one category.
|
||||
|
||||
Using these endpoints, you can list or retrieve a category's details and
|
||||
Using these API Routes, you can list or retrieve a category's details and
|
||||
products.
|
||||
externalDocs:
|
||||
description: How to use product categories in a storefront
|
||||
@@ -100,7 +100,7 @@ tags:
|
||||
such as marketing or discount purposes. For example, you can create a
|
||||
Summer Collection.
|
||||
|
||||
Using these endpoints, you can list or retrieve a collection's details and
|
||||
Using these API Routes, you can list or retrieve a collection's details and
|
||||
products.
|
||||
- name: Product Tags
|
||||
description: |
|
||||
|
||||
Reference in New Issue
Block a user