Custom API Routes

An API Route is a REST API endpoint.

An API Route is created in a TypeScript or JavaScript file under the /src/api directory of your Medusa application. The file’s name must be route.ts or route.js.

Learn more about API Routes in this documentation

For example, to create a GET API Route at /store/hello-world, create the file src/api/store/hello-world/route.ts with the following content:

import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  res.json({
    message: "Hello world!",
  });
}

Supported HTTP methods

The file based routing supports the following HTTP methods:

• GET

• POST

• PUT

• PATCH

• DELETE

• OPTIONS

• HEAD

You can define a handler for each of these methods by exporting a function with the name of the method in the paths route.ts file.

For example:

import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  // Handle GET requests
}

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  // Handle POST requests
}

export async function PUT(req: MedusaRequest, res: MedusaResponse) {
  // Handle PUT requests
}

Parameters

To create an API route that accepts a path parameter, create a directory within the route's path whose name is of the format [param].

For example, if you want to define a route that takes a productId parameter, you can do so by creating a file called /api/products/[productId]/route.ts:

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const { productId } = req.params;

  res.json({
    message: `You're looking for product ${productId}`
  })
}

To create an API route that accepts multiple path parameters, create within the file's path multiple directories whose names are of the format [param].

For example, if you want to define a route that takes both a productId and a variantId parameter, you can do so by creating a file called /api/products/[productId]/variants/[variantId]/route.ts.

Using the container

The Medusa container is available on req.scope. Use it to access modules' main services and other registered resources:

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"

export const GET = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  const productModuleService = req.scope.resolve("product")

  const [, count] = await productModuleService.listAndCount()

  res.json({
    count,
  })
}

Middleware

You can apply middleware to your routes by creating a file called /api/middlewares.ts. This file must export a configuration object with what middleware you want to apply to which routes.

For example, if you want to apply a custom middleware function to the /store/custom route, you can do so by adding the following to your /api/middlewares.ts file:

import { defineMiddlewares } from "@medusajs/framework/http"
import type {
  MedusaRequest,
  MedusaResponse,
  MedusaNextFunction,
} from "@medusajs/framework/http";

async function logger(
  req: MedusaRequest,
  res: MedusaResponse,
  next: MedusaNextFunction
) {
  console.log("Request received");
  next();
}

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/custom",
      middlewares: [logger],
    },
  ],
})

The matcher property can be either a string or a regular expression. The middlewares property accepts an array of middleware functions.