# Routes

Requests sent to Strapi on any URL are handled by routes. By default, Strapi generates routes for all the content-types (see REST API documentation). Routes can be added and configured:

  • with policies, which are a way to block access to a route,
  • and with middlewares, which are a way to control and change the request flow and the request itself.

Once a route exists, reaching it executes some code handled by a controller (see controllers documentation).

# Implementation

Implementing a new route consists in defining it in a router file within the .src/api/[apiName]/routes folder (see project structure).

A router file consists of an array of objects, each object being a route with the following parameters:

Parameter Description Type
method Method associated to the route (i.e. GET, POST, PUT, DELETE or PATCH) String
path Path to reach, starting with a forward-leading slash (e.g. /articles) String
handler Function to execute when the route is reached.
Should follow this syntax: <controllerName>.<actionName>		 String
config

Optional		 Configuration to handle policies, middlewares and public availability for the route

 Object

Generic implementation example:

To handle any GET request on the /articles path by calling the actionName function from the controllerName controller, use the following code:

// path: ./src/api/[apiName]/routes/[routerName].js (e.g './src/api/blog/routes/articles.js')

module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/articles',
      handler: 'controllerName.actionName',
    },
  ],
};

The router used by Strapi allows the creation of dynamic routes, using parameters and regular expressions. These parameters will be exposed in the ctx.params object. For more details, please refer to the PathToRegex (opens new window) documentation.

Example of routes using URL parameters and regular expressions 
// path: ./src/api/[apiName]/routes/[routerName].js (e.g './src/api/blog/routes/articles.js')

module.exports = {
  routes: [
    { // Path defined with a URL parameter
      method: 'GET',
      path: '/restaurants/:category/:id',
      handler: 'Restaurant.findOneByCategory',
    },
    { // Path defined with a regular expression
      method: 'GET',
      path: '/restaurants/:region(\\d{2}|\\d{3})/:id', // Only match when the first parameter contains 2 or 3 digits.
      handler: 'Restaurant.findOneByRegion',
    }
  ]
}

# Configuration

The optional configuration for a route is defined in its config object, which can be used to handle policies and middlewares or to make the route public.

# Policies

Policies can be added to a route configuration:

  • by pointing to a policy registered in ./src/policies, with or without passing a custom configuration
  • or by declaring the policy implementation directly, as a function that takes policyContext to extend Koa's context (opens new window) (ctx) and the strapi instance as arguments (see policies documentation)
// path: ./src/api/[apiName]/routes/[routerName].js (e.g './src/api/blog/routes/articles.js')

module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/articles',
      handler: 'controllerName.actionName',
      config: {
        policies: [
          'policy-name', // point to a registered policy
          { name: 'policy-name', config: {} }, // point to a registered policy with some custom configuration
          // pass a policy implementation directly
          (policyContext, config, { strapi }) => {
            return true;
          },
        ],
      },
    },
  ],
};

# Middlewares

Middlewares can be added to a route configuration:

  • by pointing to a middleware registered in ./src/middlewares, with or without passing a custom configuration
  • or by declaring the middleware implementation directly, as a function that takes Koa's context (opens new window) (ctx) and the strapi instance as arguments:
// path: ./src/api/[apiName]/routes/[routerName].js (e.g './src/api/blog/routes/articles.js')

module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/articles',
      handler: 'controllerName.actionName',
      config: {
        middlewares: [
          'middleware-name', // point to a registered middleware
          { name: 'middleware-name', config: {} }, // point to a registered middleware with some custom configuration
          // pass a middleware implementation directly
          (ctx, next) => {
            return next();
          },
        ],
      },
    },
  ],
};

# Public routes

By default, routes are protected by Strapi's authentication system, which is based on API tokens or the use of a plugin such as the Users & Permissions plugin.

In some scenarios, it can be useful to have a route publicly available and control the access outside of the normal Strapi authentication system. This can be achieved by setting the auth configuration parameter of a route to false:

// path: ./src/api/[apiName]/routes/[routerName].js (e.g './src/api/blog/routes/articles.js')

module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/articles',
      handler: 'controllerName.actionName',
      config: {
        auth: false,
      },
    },
  ],
};

← Policies →