How to Create an API Route
In this document, you’ll learn how to create API Routes in Medusa.
v1.17.2 of @medusajs/medusa
introduced API Routes to replace Express endpoints. You can still use the Express endpoints approach, however, it's highly recommended that you start using API Routes.
Basic Implementation
API Route Path
Custom API Routes must be created in a file named route.ts
or route.js
under the src/api
directory of your Medusa backend or plugin. The API Route's path will be the same as the path of its corresponding route.ts
file relative to src/api
.
For example, if you're creating the API route store/custom
, you must create the file src/api/store/custom/route.ts
.
API Route Method
route.ts
can export at least one of the following method handler functions: GET
, POST
, DELETE
, PUT
, PATCH
, OPTIONS
, and HEAD
. Defining these method handlers adds a new API Route for the corresponding HTTP method at the same path.
Each of these method handler functions receives two parameters: the MedusaRequest
which extends Express's Request, and the MedusaResponse
which extends Response. Both are imported from @medusajs/medusa
.
In the example above, GET
and POST
API Routes will be added at the store/custom
path.
Building Files
Custom API Routes must be transpiled and moved to the dist
directory before you can start consuming them. When you run your backend using either the medusa develop
or npx medusa develop
commands, it watches the files under src
for any changes, then triggers the build
command and restarts the server.
However, the build isn't triggered when the backend first starts running, and it's never triggered when the medusa start
or npx medusa start
commands are used.
So, make sure to run the build
command before starting the backend and testing out your API Routes:
Medusa API Routes Path Convention
Although your API Route can be under any path you wish, the Medusa backend uses the following conventions:
- All storefront REST APIs are prefixed by
/store
. For example, the/store/products
API Route lets you retrieve the products to display them on your storefront. - All admin REST APIs are prefixed by
/admin
. For example, the/admin/products
API Route lets you retrieve the products to display them on your admin.
Path Parameters
If your API Route accepts a path parameter, you can place its route file inside a directory with the name [<PARAMETER_NAME>]
, where <PARAMETER_NAME>
is the name of your parameter.
For example, to add an API Route at the path store/custom/[id]
, create the route file at src/api/store/custom/[id]/route.ts
.
You can access a path parameter's value in method handlers using the MedusaRequest
object's params
property, which is an object. Each of the params
keys is a path parameter's name, and its value is the supplied value when sending the request to the API route.
For example:
An API Route can have more than one path parameter, but each path parameter's nam is unique. If the same path parameter name is used more than once in the same route path, it results in an error and the Medusa Backend won't register the API Route.
For example, if your API route accepts an author ID and a post ID, the path to your route file can be src/api/author/[id]/posts/[post_id]/route.ts
. You can then use the MedusaRequest
object's params.id
and params.post_id
to access the values of the path parameters.
CORS Configuration
The cors
middleware, which enables Cross-Origin Resource Sharing (CORS), is automatically applied on custom API Routes defined under the /store
or /admin
path prefixes based on the respective store_cors and admin_cors configurations.
To add CORS configurations to custom API routes under other path prefixes, or override the CORS configurations added by default, define a middleware on your API routes and pass it the cors
middleware. For example:
CORS Opt-Out
To disable the cors
middleware for an API Route, export a CORS
variable in the route file with its value set to false
.
For example:
Parse Request Body Parameters
By default, the Medusa backend parses the body of all requests sent to your API Routes with the Content-Type
header set to application/json
to a JavaScript object. Then, the parsed data is attached to the MedusaRequest
object's body
property, which is an object.
Each of the body
's keys are a name of the request body parameters, and its value is the passed value in the request body.
For example:
If you want to parse other content types, such as application/x-www-form-urlencoded
, you have to add a middleware to your API routes that parses that body type.
For example:
Note that the urlencoded
middleware imported from the body-parser package attaches the parsed data to the MedusaRequest
object's body
property as well.
Parse Webhook Body Parameters
For webhook API Routes, you may need to use the raw
body parser middleware rather than the default json
.
You can opt out of the default body parser by setting the bodyParser
property of a middleware route object to false
, and passing the preferred body-parser middleware in the middlewares
property.
For example:
You can also disable the default json
body parser for specific HTTP methods using the method
property for a middleware route object. Its value can either be a string or an array of strings, each being an HTTP method name.
For example:
This disables the default JSON body parser for the POST and PUT HTTP methods on API Routes matching the /webhooks/*
matcher, and applies the raw
body-parser middleware on them instead.
Configure Request Body Size Limit
By default, the maximum request body size allowed is 1000
bytes. If a request body's size is greater than that, an error is thrown.
If you expect the request body of an API Route to be larger than the default, you can set the bodyParser
property of a middleware route object to a configuration object with the property sizeLimit
. Its value is a number indicating the maximum allowed size limit in bytes.
For example:
Protected API Routes
Protected API routes are routes that should only be accessible by logged-in customers or users.
Protect Store API Routes
By default, API routes prefixed by /store
don't require customer authentication to access the API route. However, you can still access the logged-in customer's ID in the API Route method handler using the MedusaRequest
object's user.customer_id
, which will be undefined
if the customer isn't logged in.
For example:
import { CustomerService } from "@medusajs/medusa"
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/medusa"
export const GET = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const id = req.user.customer_id
if (!id) {
// TODO handle not logged in
// customers based on the custom
// API route's functionality
}
const customerService = req.scope.resolve<CustomerService>(
"customerService"
)
const customer = await customerService.retrieve(id)
// ...
}
API Routes prefixed by /store/me
, on the other hand, require customer authentication to access the API Route. You can access the logged-in customer's ID in the API Route method handler using the MedusaRequest
object's user.customer_id
.
If you want to disable authentication requirement on your custom API Route prefixed with /store/me
, export an AUTHENTICATE
variable in the route file with its value set to false
. For example:
This disables authentication requirement on all API Route methods defined in the same file.
Protect Admin API Routes
By default, all API Routes prefixed by /admin
require admin user authentication to access the API Route. You can access the logged-in user's ID in the API Route method handler using the MedusaRequest
object's user.userId
.
For example:
import type {
MedusaRequest,
MedusaResponse,
UserService,
} from "@medusajs/medusa"
export const GET = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const id = req.user.userId
const userService = req.scope.resolve<UserService>(
"userService"
)
const user = await userService.retrieve(id)
// ...
}
To disable authentication requirement on an admin API Route, export an AUTHENTICATE
variable in your route file with its value set to false
.
For example:
This disables authentication requirement on all API Route methods defined in the same file.
Protect Other API Routes
To protect API routes that aren't prefixed with /store
or /admin
, you can use one of the following middlewares exported by @medusajs/medusa
for authenticating customers or users:
authenticate
: this middleware ensures that only authenticated admin users can access an API Route. You can access the user's ID in the API Route method handler using theMedusaRequest
object'suser.userId
.authenticateCustomer
: this middleware doesn't require a customer to be authenticated, but if a customer is logged in, it attaches their ID to theMedusaRequest
object'suser.customer_id
.requireCustomerAuthentication
: this middleware ensures that only authenticated customers can access an API Route. You can access the customer's ID in the API Route method handler using theMedusaRequest
object'suser.customer_id
.
For example:
import {
authenticate,
requireCustomerAuthentication,
type MiddlewaresConfig,
} from "@medusajs/medusa"
export const config: MiddlewaresConfig = {
routes: [
{
matcher: "/custom/admin*",
middlewares: [authenticate()],
},
{
matcher: "/custom/customer*",
middlewares: [requireCustomerAuthentication()],
},
],
}
Retrieve Medusa Config
You can access the configurations exported in medusa-config.js
, including your custom configurations, by resolving the configModule
resource using dependency injection.
For example:
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/medusa"
import { ConfigModule } from "@medusajs/medusa"
// This is only helpful if you're
// accessing custom configurations
// otherwise it's fine to just use `ConfigModule`
type MyConfigModule = ConfigModule & {
projectConfig: {
custom_config?: string
}
}
export const GET = (
req: MedusaRequest,
res: MedusaResponse
) => {
const configModule = req.scope.resolve<MyConfigModule>(
"configModule"
)
res.json({
message: configModule.projectConfig.custom_config,
})
}
Handle Errors
Medusa automatically applies an error-handler middleware on your custom API routes, which returns errors as a JSON response whose format is consistent with the Medusa backend.
When an error is thrown, the response status code is set to 500
by default. However, that changes based on the MedusaError
type thrown as explained in the next section.
Medusa Error Types
You must throw errors of type MedusaError
to ensure the error message is returned in the response. Otherwise, the returned error message will be Unknown Error
.
For example, if you throw an error like this:
The API Route returns the following object error in the response:
To ensure your error message is relayed in the response, use MedusaError
imported from @medusajs/utils
as the thrown error type instead.
For example:
The constructor of MedusaError
accepts the following parameters:
- The first parameter is the error's type. You can use one of the predefined errors under
MedusaError.Types
, such asMedusaError.Types.NOT_FOUND
which sets the response status code to404
automatically. - The second parameter is the message of the error.
- The third parameter is an optional code, which is a string, that's returned in the error object.
After using MedusaError
, the returned error in the response provides a clearer message:
Available MedusaError Types and their respective status codes
Override Error Handler
To override the default error handler, pass the errorHandler
property to the exported middleware configurations with the custom error-handler middleware as its value.
For example:
Disable Default Error Handler
To disable the default error handler, set the errorHandler
property of the exported middleware configurations to false
.
For example:
However, when you disable the default error handler, errors thrown in an async
function or method are not handled and requests goes on indefinitely with no response.
To ensure that errors are still returned in the response when the default error handler is disabled, either create a custom error handler or wrap your API Route with the wrapHandler
imported from @medusajs/medusa
.
For example:
Use Other Resources
Resources, such as services, that are registered in the dependency container can be retrieved in an API Route's handler method using the MedusaRequest
object's scope.resolve
method.
The scope
method accepts as a parameter the resource's registration name in the dependency container.
Example: Retrieve Repository
Posts are represented by a custom entity not covered in this guide. You can refer to the entities for more details on how to create a custom entity.
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/medusa"
import {
PostRepository,
} from "../../../repositories/post"
import { EntityManager } from "typeorm"
export const GET = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const postRepository =
req.scope.resolve<PostRepository>("postRepository")
const manager = req.scope.resolve<EntityManager>("manager")
const postRepo = manager.withRepository(postRepository)
res.json({
posts: await postRepo.find(),
})
}
Notice that to retrieve an instance of the repository, you need to retrieve first Typeorm's Entity Manager from the dependency container, then use its withRepository
method.
Example: Retrieve Service
PostService
is a custom service that is not covered in this guide. You can refer to the services documentation for more details on how to create a custom service, and find an example of PostService
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/medusa"
import { PostService } from "../../../services/post"
export const GET = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const postService: PostService = req.scope.resolve(
"postService"
)
res.json({
posts: await postService.list(),
})
}
Ignored Files and Directories
Files and directories prefixed with _
are ignored. This can be helpful if you want to implement API Route method handlers in different files, then reference them in your route.ts
file.
For example:
import {
MedusaRequest,
MedusaResponse,
ProductService,
} from "@medusajs/medusa"
export default async function (
req: MedusaRequest,
res: MedusaResponse
) {
const productService = req.scope.resolve<ProductService>(
"productService"
)
const products = await productService.list({})
res.json({
products,
})
}
Example: CRUD API Routes
This section provides an example of creating API Routes that perform Create, Read, Update, and Delete (CRUD) operations.
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/medusa"
import { PostService } from "../../../services/post"
// list posts
export const GET = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const postService: PostService = req.scope.resolve(
"postService"
)
res.json({
posts: await postService.list(),
})
}
// create a post
export const POST = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const postService: PostService = req.scope.resolve(
"postService"
)
// basic validation of request body
if (!req.body.title || !req.body.author_id) {
throw new Error("`title` and `author_id` are required.")
}
const post = await postService.create(req.body)
res.json({
post,
})
}
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/medusa"
import { PostService } from "../../../services/post"
// retrieve a post by its ID
export const GET = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const postService: PostService = req.scope.resolve(
"postService"
)
const post = await postService.retrieve(req.params.id)
res.json({
post,
})
}
// update a post by its ID
export const POST = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const postService: PostService = req.scope.resolve(
"postService"
)
// basic validation of request body
if (req.body.id) {
throw new Error("Can't update post ID")
}
const post = await postService.update(
req.params.id,
req.body
)
res.json({
post,
})
}
// delete a post by its ID
export const DELETE = async (
req: MedusaRequest,
res: MedusaResponse
) => {
const postService: PostService = req.scope.resolve(
"postService"
)
await postService.delete(req.params.id)
res.status(200).end()
}