# 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).

There are two different router file structures depending on if you are configuring the core routers or creating your own custom routers. Strapi provides a createCoreRouter factory function that automatically generates and allows for configuration of the core routers.

# Core Routers

For core routers (find, findOne, create, update, and delete), a default file is created that allows passing in some configuration options to each router and allowing you to disable certain core routers so you can create your own custom ones. The core router file structure has the following parameters:

Parameter Description Type
prefix Allows passing in a custom prefix to add to all routers for this model (e.g. /test) String
only Array of core routes that will only be loaded, anything not in this array is ignored Array
except Array of core routes that should not be loaded, functionally the opposite of the only option Array
config Configuration to handle policies, middlewares and public availability for the route Object

Full Core Router configuration example:

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
  prefix: '',
  only: ['find', 'findOne'],
  except: [],
  config: {
    find: {
      auth: false,
      policies: [],
      middlewares: [],
    },
    findOne: {},
    create: {},
    update: {},
    delete: {},
  },
});

Generic implementation example:

To only allow a GET request on the /restaurants path from the core find controller without authentication, use the following code:

Example of disabling authentication on a core route 
// path: ./src/api/[apiName]/routes/[routerName].js (e.g './src/api/restaurant/routes/restaurant.js')

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
  only: ['find'],
  config: {
    find: {
      auth: false
      policies: [],
      middlewares: [],
    }
  }
});

# Custom Routers

For custom routers you will need to generate another router file that doesn't use the createCoreRouter factory this 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:

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/restaurant/routes/custom-restaurant.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

Both the core routers and any custom routers you define in additional files have the same configuration options and 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)

# 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:

# 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:

← Policies →