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.
2023-10-19 15:56:26 +00:00
parent b38f73726d
commit c28935b4e8
170 changed files with 3658 additions and 3344 deletions
@@ -21,11 +21,11 @@ export interface AdminPostProductsProductReq {
   */
  discountable?: boolean
  /**
-   * An array of images of the Product. Each value in the array is a URL to the image. You can use the upload endpoints to upload the image and obtain a URL.
+   * An array of images of the Product. Each value in the array is a URL to the image. You can use the upload API Routes to upload the image and obtain a URL.
   */
  images?: Array<string>
  /**
-   * The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload endpoints to upload the thumbnail and obtain a URL.
+   * The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload API Routes to upload the thumbnail and obtain a URL.
   */
  thumbnail?: string
  /**
@@ -25,11 +25,11 @@ export interface AdminPostProductsReq {
   */
  discountable?: boolean
  /**
-   * An array of images of the Product. Each value in the array is a URL to the image. You can use the upload endpoints to upload the image and obtain a URL.
+   * An array of images of the Product. Each value in the array is a URL to the image. You can use the upload API Routes to upload the image and obtain a URL.
   */
  images?: Array<string>
  /**
-   * The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload endpoints to upload the thumbnail and obtain a URL.
+   * The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload API Routes to upload the thumbnail and obtain a URL.
   */
  thumbnail?: string
  /**
@@ -5,7 +5,7 @@ import { SetRelation, Merge } from "../core/ModelUtils"

 export interface StorePostCustomersCustomerAcceptClaimReq {
  /**
-   * The claim token generated by previous request to the Claim Order endpoint.
+   * The claim token generated by previous request to the Claim Order API Route.
   */
  token: string
 }
@@ -21,7 +21,7 @@ export interface StorePostReturnsReq {
     */
    quantity: number
    /**
-     * The ID of the return reason. Return reasons can be retrieved from the List Return Reasons endpoint.
+     * The ID of the return reason. Return reasons can be retrieved from the List Return Reasons API Route.
     */
    reason_id?: string
    /**
@@ -21,7 +21,7 @@ export interface StorePostSwapsReq {
     */
    quantity: number
    /**
-     * The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons endpoint.
+     * The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons API Route.
     */
    reason_id?: string
    /**
@@ -9,10 +9,10 @@ tags:
  - name: Apps Oauth
    description: |
      Some plugins may require to authenticate with third-party services and store authentication details, such as the authentication token. To do 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 app using its oauth provider.
+      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 as login or log out.
+      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 admin's login session.
    externalDocs:
      description: How to implement user profiles
@@ -20,14 +20,14 @@ tags:
  - name: Batch Jobs
    description: |
      A batch job is a task that is performed by the Medusa backend asynchronusly. For example, the Import Product feature is implemented using batch jobs.
-      Batch Job endpoints allows admins to manage the batch jobs and their state.
+      Batch Job API Routes allows admins to manage the batch jobs and their state.
    externalDocs:
      description: How to import products
      url: https://docs.medusajs.com/modules/products/admin/import-products
  - name: Currencies
    description: |
      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 admins to list and update currencies.
+      Currencies are defined within the Medusa backend. Currency API Routes allow admins to list and update currencies.
    externalDocs:
      description: How to manage currencies
      url: https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies
@@ -47,7 +47,7 @@ tags:
  - name: Discounts
    description: |
      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, resources, and more.
+      The Discount API Routes can be used to manage discounts, their conditions, resources, and more.
    externalDocs:
      description: How to manage discounts
      url: https://docs.medusajs.com/modules/discounts/admin/manage-discounts
@@ -60,7 +60,7 @@ tags:
  - name: Gift Cards
    description: |
      Admins can create gift cards and send them directly to customers, 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.
+      These gift cards are different than the saleable gift cards in a store, which are created and managed through Product API Routes.
    externalDocs:
      description: How to manage gift cards
      url: https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards
@@ -134,14 +134,14 @@ tags:
  - name: Product Variants
    description: |
      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: https://docs.medusajs.com/modules/products/admin/manage-products#manage-product-variants
  - name: Publishable API Keys
    description: |
      Publishable API Keys can be used to scope Store API calls with an API key, determining what resources are retrieved when querying the API.
-      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,
+      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 API Route,
      the sales channels are inferred from the key and only products associated with those sales channels are retrieved.
      Admins can manage publishable API keys and their associated resources. Currently, only Sales Channels are supported as a resource.
    externalDocs:
@@ -222,7 +222,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 example, they can be used to upload CSV files that are used to import products into the store.
+      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:
      description: How to upload CSV file when importing a product.
      url: https://docs.medusajs.com/modules/products/admin/import-products#1-upload-csv-file
@@ -8,7 +8,7 @@ info:
 tags:
  - name: Auth
    description: |
-      Authentication endpoints allow customers to manage their session, such as login or log out.
+      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 customer's login session.
    externalDocs:
      description: How to implement customer profiles in your storefront
@@ -29,14 +29,14 @@ tags:
  - name: Gift Cards
    description: |
      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
  - name: Orders
    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: https://docs.medusajs.com/modules/orders/storefront/retrieve-order-details
@@ -53,7 +53,7 @@ tags:
  - name: Products
    description: |
      Products are saleable items in a store. This also includes [saleable gift 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, sales channels, and more.
+      Using these API Routes, you can filter products by categories, collections, sales channels, and more.
    externalDocs:
      description: How to show products in a storefront
      url: https://docs.medusajs.com/modules/products/storefront/show-products
@@ -63,14 +63,14 @@ tags:
  - name: Product Categories
    description: |
      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 products.
+      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
      url: https://docs.medusajs.com/modules/products/storefront/use-categories
  - name: Product Collections
    description: |
      A product collection is used to organize products for different purposes 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 products.
+      Using these API Routes, you can list or retrieve a collection's details and products.
  - name: Product Tags
    description: |
      Product tags are string values that can be used to filter products by.
@@ -4,7 +4,7 @@
 * summary: "User Logout"
 * x-authenticated: true
 * description: "Delete the current session for the logged in user. This will only work if you're using Cookie session for authentication. If the API token is still passed in the header,
- * the user is still authorized to perform admin functionalities in other endpoints."
+ * the user is still authorized to perform admin functionalities in other API Routes."
 * x-codegen:
 *   method: deleteSession
 * x-codeSamples:
@@ -5,7 +5,7 @@ import { EntityManager } from "typeorm"
 * @oas [post] /admin/batch-jobs/{id}/confirm
 * operationId: "PostBatchJobsBatchJobConfirmProcessing"
 * summary: "Confirm a Batch Job"
- * description: "When a batch job is created, it is not executed automatically if `dry_run` is set to `true`. This endpoint confirms that the batch job should be executed."
+ * description: "When a batch job is created, it is not executed automatically if `dry_run` is set to `true`. This API Route confirms that the batch job should be executed."
 * x-authenticated: true
 * parameters:
 *   - (path) id=* {string} The ID of the batch job.
@@ -10,7 +10,7 @@ import { validator } from "../../../../utils/validator"
 * operationId: "PostBatchJobs"
 * summary: "Create a Batch Job"
 * description: "Create a Batch Job to be executed asynchronously in the Medusa backend. If `dry_run` is set to `true`, the batch job will not be executed until the it is confirmed,
- *  which can be done using the Confirm Batch Job endpoint."
+ *  which can be done using the Confirm Batch Job API Route."
 * externalDocs:
 *   description: "How to create a batch job"
 *   url: "https://docs.medusajs.com/development/batch-jobs/create#create-batch-job"
@@ -54,7 +54,7 @@ import IsolateProductDomainFeatureFlag from "../../../../loaders/feature-flags/i
 * operationId: "PostProducts"
 * summary: "Create a Product"
 * x-authenticated: true
- * description: "Create a new Product. This endpoint can also be used to create a gift card if the `is_giftcard` field is set to `true`."
+ * description: "Create a new Product. This API Route can also be used to create a gift card if the `is_giftcard` field is set to `true`."
 * requestBody:
 *   content:
 *     application/json:
@@ -408,12 +408,12 @@ class ProductVariantReq {
 *     type: boolean
 *     default: true
 *   images:
- *     description: An array of images of the Product. Each value in the array is a URL to the image. You can use the upload endpoints to upload the image and obtain a URL.
+ *     description: An array of images of the Product. Each value in the array is a URL to the image. You can use the upload API Routes to upload the image and obtain a URL.
 *     type: array
 *     items:
 *       type: string
 *   thumbnail:
- *     description: The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload endpoints to upload the thumbnail and obtain a URL.
+ *     description: The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload API Routes to upload the thumbnail and obtain a URL.
 *     type: string
 *   handle:
 *     description: A unique handle to identify the Product by. If not provided, the kebab-case version of the product title will be used. This can be used as a slug in URLs.
@@ -434,12 +434,12 @@ class ProductVariantReq {
 *     description: A flag to indicate if discounts can be applied to the Line Items generated from this Product
 *     type: boolean
 *   images:
- *     description: An array of images of the Product. Each value in the array is a URL to the image. You can use the upload endpoints to upload the image and obtain a URL.
+ *     description: An array of images of the Product. Each value in the array is a URL to the image. You can use the upload API Routes to upload the image and obtain a URL.
 *     type: array
 *     items:
 *       type: string
 *   thumbnail:
- *     description: The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload endpoints to upload the thumbnail and obtain a URL.
+ *     description: The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload API Routes to upload the thumbnail and obtain a URL.
 *     type: string
 *   handle:
 *     description: A unique handle to identify the Product by. If not provided, the kebab-case version of the product title will be used. This can be used as a slug in URLs.
@@ -7,7 +7,7 @@ import { PaymentProvider } from "../../../../models"
 * @oas [get] /store/customers/me/payment-methods
 * operationId: GetCustomersCustomerPaymentMethods
 * summary: Get Saved Payment Methods
- * description: "Retrieve the logged-in customer's saved payment methods. This endpoint only works with payment providers created with the deprecated Payment Service interface.
+ * description: "Retrieve the logged-in customer's saved payment methods. This API Route only works with payment providers created with the deprecated Payment Service interface.
 *  The payment methods are saved using the Payment Service's third-party service, and not on the Medusa backend. So, they're retrieved from the third-party service."
 * x-authenticated: true
 * deprecated: true
@@ -7,7 +7,7 @@ import { EntityManager } from "typeorm"
 * @oas [post] /store/customers/password-token
 * operationId: PostCustomersCustomerPasswordToken
 * summary: Request Password Reset
- * description: "Create a reset password token to be used in a subsequent Reset Password endpoint. This emits the event `customer.password_reset`. If a notification provider is
+ * description: "Create a reset password token to be used in a subsequent Reset Password API Route. This emits the event `customer.password_reset`. If a notification provider is
 *  installed in the Medusa backend and is configured to handle this event, a notification to the customer, such as an email, may be sent with reset instructions."
 * externalDocs:
 *   description: "How to reset password"
@@ -10,7 +10,7 @@ import { MedusaError } from "medusa-core-utils"
 * @oas [post] /store/customers/password-reset
 * operationId: PostCustomersResetPassword
 * summary: Reset Password
- * description: "Reset a Customer's password using a password token created by a previous request to the Request Password Reset endpoint. If the password token expired,
+ * description: "Reset a Customer's password using a password token created by a previous request to the Request Password Reset API Route. If the password token expired,
 *  you must create a new one."
 * externalDocs:
 *   description: "How to reset password"
@@ -12,7 +12,7 @@ import {
 * @oas [post] /store/order-edits/{id}/complete
 * operationId: "PostOrderEditsOrderEditComplete"
 * summary: "Complete an Order Edit"
- * description: "Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the Payment Collection endpoints."
+ * description: "Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the Payment Collection API Routes."
 * externalDocs:
 *   description: "How to handle order edits in a storefront"
 *   url: "https://docs.medusajs.com/modules/orders/storefront/handle-order-edits"
@@ -118,7 +118,7 @@ export default async (req, res) => {
 *   - token
 * properties:
 *   token:
- *     description: "The claim token generated by previous request to the Claim Order endpoint."
+ *     description: "The claim token generated by previous request to the Claim Order API Route."
 *     type: string
 */
 export class StorePostCustomersCustomerAcceptClaimReq {
@@ -9,7 +9,7 @@ import { TokenEvents } from "../../../../types/token"
 * @oas [post] /store/orders/batch/customer/token
 * operationId: "PostOrdersCustomerOrderClaim"
 * summary: "Claim Order"
- * description: "Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the endpoint Verify Order Claim.
+ * description: "Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the Verify Order Claim API Route.
 *  This also emits the event `order-update-token.created`. So, if you have a notification provider installed that handles this event and sends the customer a notification, such as an email,
 *  the customer should receive instructions on how to finalize their claim ownership."
 * externalDocs:
@@ -12,7 +12,7 @@ import { defaultStoreCategoryScope } from "."
 * operationId: "GetProductCategories"
 * summary: "List Product Categories"
 * description: "Retrieve a list of product categories. The product categories can be filtered by fields such as `handle` or `q`. The product categories can also be paginated.
- *  This endpoint can also be used to retrieve a product category by its handle."
+ *  This API Route can also be used to retrieve a product category by its handle."
 * x-featureFlag: "product_categories"
 * externalDocs:
 *   description: "How to retrieve a product category by its handle"
@@ -32,7 +32,7 @@ import { defaultStoreProductRemoteQueryObject } from "./index"
 * summary: List Products
 * description: |
 *   Retrieves a list of products. The products can be filtered by fields such as `id` or `q`. The products can also be sorted or paginated.
- *   This endpoint can also be used to retrieve a product by its handle.
+ *   This API Route can also be used to retrieve a product by its handle.
 *
 *   For accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as
 *   `region_id`, `currency_code`, and `cart_id` when available.
@@ -11,7 +11,7 @@ import { validator } from "../../../../utils/validator"
 * @oas [get] /store/regions
 * operationId: GetRegions
 * summary: List Regions
- * description: "Retrieve a list of regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated. This endpoint is useful to
+ * description: "Retrieve a list of regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated. This API Route is useful to
 *  show the customer all available regions to choose from."
 * externalDocs:
 *   description: "How to use regions in a storefront"
@@ -280,7 +280,7 @@ class Item {
 *           description: The quantity to return.
 *           type: integer
 *         reason_id:
- *           description: The ID of the return reason. Return reasons can be retrieved from the List Return Reasons endpoint.
+ *           description: The ID of the return reason. Return reasons can be retrieved from the List Return Reasons API Route.
 *           type: string
 *         note:
 *           description: A note to add to the item returned.
@@ -24,7 +24,7 @@ import { validator } from "../../../../utils/validator"
 * summary: Create a Swap
 * description: |
 *   Create a Swap for an Order. This will also create a return and associate it with the swap. If a return shipping option is specified, the return will automatically be fulfilled.
- *   To complete the swap, you must use the Complete Cart endpoint passing it the ID of the swap's cart.
+ *   To complete the swap, you must use the Complete Cart API Route passing it the ID of the swap's cart.
 *
 *   An idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to
 *   the response. If an error occurs during swap creation or the request is interrupted for any reason, the swap creation can be retried by passing the idempotency
@@ -316,7 +316,7 @@ class AdditionalItem {
 *           description: The quantity to return.
 *           type: integer
 *         reason_id:
- *           description: The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons endpoint.
+ *           description: The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons API Route.
 *           type: string
 *         note:
 *           description: The note to add to the item being swapped.