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.

www/apps/docs/content/development/idempotency-key/overview.mdx

@@ -11,7 +11,7 @@ In this document, you'll learn what an idempotency key is in Medusa.
 
 ## Overview
 
-An Idempotency Key is a unique, randomly generated key associated with an operation, such as the cart completion process. The idempotency key can be passed in the header of a request to an endpoint. This allows you to safely retry requests without accidentally performing the same operation twice.
+An Idempotency Key is a unique, randomly generated key associated with an operation, such as the cart completion process. The idempotency key can be passed in the header of a request to an API Route. This allows you to safely retry requests without accidentally performing the same operation twice.
 
 For example, if a connection error occurs while the customer is completing their cart and placing an order, you can retry from the last recovery point before the error occurred.
 

www/apps/docs/content/development/idempotency-key/use-service.md

@@ -9,7 +9,7 @@ In this document, you'll learn how to use the `IdempotencyKeyService`.
 
 ## Overview
 
-You can use the `IdempotencyKeyService` within your custom development to ensure that your custom endpoints and operations can be safely retried or continued if an error occurs. This guide is also useful if you're overriding an existing feature in Medusa that uses the `IdempotencyKeyService` and you want to maintain its usage, such as if you're overriding the cart completion strategy.
+You can use the `IdempotencyKeyService` within your custom development to ensure that your custom API Routes and operations can be safely retried or continued if an error occurs. This guide is also useful if you're overriding an existing feature in Medusa that uses the `IdempotencyKeyService` and you want to maintain its usage, such as if you're overriding the cart completion strategy.
 
 The `IdempotencyKeyService` includes methods that can be used to create and update idempotency keys, among other functionalities.
 
@@ -17,18 +17,30 @@ The `IdempotencyKeyService` includes methods that can be used to create and upda
 
 ## Create Idempotency Key
 
-You can create an idempotency key within an endpoint using the `create` method of the `IdempotencyKeyService`:
+You can create an idempotency key within an API Route using the `create` method of the `IdempotencyKeyService`:
 
-```ts
-router.post("/custom-route", async (req, res) => {
+```ts title=src/api/store/custom/route.ts
+import type { 
+  MedusaRequest, 
+  MedusaResponse,
+} from "@medusajs/medusa"
+import { IdempotencyKeyService } from "@medusajs/medusa"
+
+export const POST = async (
+  req: MedusaRequest, 
+  res: MedusaResponse
+) => {
   // ...
+  const idempotencyKeyService = req.scope.resolve<
+    IdempotencyKeyService
+  >("idempotencyKeyService")
   const idempotencyKey = await idempotencyKeyService.create({
     request_method: req.method,
     request_params: req.params,
     request_path: req.path,
   })
   // ...
-})
+}
 ```
 
 The method requires as a parameter an object having the following properties:
@@ -41,9 +53,23 @@ The method handles generating the idempotency key value and saving the idempoten
 
 Alternatively, you can use the `initializeRequest` method that allows you to retrieve an idempotency key based on the value passed in the `Idempotency-Key` header of the request if it exists, or create a new key otherwise. For example:
 
-```ts
-router.post("/custom-route", async (req, res) => {
+```ts title=src/api/store/custom/route.ts
+import type { 
+  MedusaRequest, 
+  MedusaResponse,
+} from "@medusajs/medusa"
+import { 
+  IdempotencyKeyService,
+} from "@medusajs/medusa"
+
+export const POST = async (
+  req: MedusaRequest, 
+  res: MedusaResponse
+) => {
   // ...
+  const idempotencyKeyService = req.scope.resolve<
+    IdempotencyKeyService
+  >("idempotencyKeyService")
   const headerKey = req.get("Idempotency-Key") || ""
 
   const idempotencyKey = await idempotencyKeyService
@@ -54,7 +80,7 @@ router.post("/custom-route", async (req, res) => {
       req.path
     )
   // ...
-})
+}
 ```
 
 The method requires the following parameters: