diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 5f31c7857f..0a894b6d5e 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -154,7 +154,7 @@ const sidebar = { collapsable: true, path: '/developer-docs/latest/development/backend-customization', children: [ - ['/developer-docs/latest/development/backend-customization/routing.md', 'Routing'], + ['/developer-docs/latest/development/backend-customization/routes.md', 'Routes'], ['/developer-docs/latest/development/backend-customization/policies.md', 'Policies'], ['/developer-docs/latest/development/backend-customization/controllers.md', 'Controllers'], ['/developer-docs/latest/development/backend-customization/requests-responses.md', 'Requests & Responses'], diff --git a/docs/developer-docs/latest/development/backend-customization/routes.md b/docs/developer-docs/latest/development/backend-customization/routes.md new file mode 100644 index 0000000000..a3f2bb1963 --- /dev/null +++ b/docs/developer-docs/latest/development/backend-customization/routes.md @@ -0,0 +1,166 @@ +--- +title: Routes - Strapi Developer Documentation +description: … +sidebarDepth: 3 +--- + + + +# 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](/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md)). Routes can be [added](#implementation) and configured: + +- with [policies](#policies), which are a way to block access to a route, +- and with [middlewares](#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](/developer-docs/latest/development/backend-customization/controllers.md) documentation). + +## Implementation + +Implementing a new route consists in defining it in a router file within the `.src/api/[apiName]/routes` folder (see [project structure](/developer-docs/latest/setup-deployment-guides/file-structure.md)). + +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: `.` | `String` | +| `config`

_Optional_ | Configuration to handle [policies](policies), [middlewares](middlewares) and [public availability](#public-routes) 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](/developer-docs/latest/development/backend-customization/controllers.md), use the following code: + +```js +// 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](https://github.com/pillarjs/path-to-regexp) documentation. + +::: details Example of routes using URL parameters and regular expressions +```js +// 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](#policies) and [middlewares](#middlewares) or to [make the route public](#public-routes). + +### Policies + +[Policies](/developer-docs/latest/development/backend-customization/policies.md) 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 [Koa's context](https://koajs.com/#context) (`ctx`) and the `strapi` instance as arguments + +```js +// 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 + (ctx, { strapi }) => { + return true; + }, + ], + }, + }, + ], +}; +``` + +### Middlewares + +[Middlewares](/developer-docs/latest/development/backend-customization/middlewares.md) 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](https://koajs.com/#context) (`ctx`) and the `strapi` instance as arguments: + +```js +// 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](/user-docs/latest/plugins/strapi-plugins.html#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`: + +```js +// 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, + }, + }, + ], +}; +``` + +*** diff --git a/docs/developer-docs/latest/development/backend-customization/routing.md b/docs/developer-docs/latest/development/backend-customization/routing.md deleted file mode 100644 index da482a2841..0000000000 --- a/docs/developer-docs/latest/development/backend-customization/routing.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: -description: ---- - - - -# Routing - -`./api/**/config/routes.json` files define all available endpoints for the clients. - -By default, Strapi generates endpoints for all your Content Types. More information is in the [Content API](/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md#api-endpoints) documentation. - -## How to create a route? - -You have to edit the `routes.json` file in one of your APIs folders (`./api/**/config/routes.json`) and manually add a new route object into the `routes` array. - -**Path —** `./api/**/config/routes.json`. - -```json -{ - "routes": [ - { - "method": "GET", - "path": "/restaurants", - "handler": "Restaurant.find", - "config": { - "policies": [] - } - }, - { - "method": "PUT", - "path": "/restaurants/bulkUpdate", - "handler": "Restaurant.bulkUpdate", - "config": { - "policies": [] - } - }, - { - "method": "POST", - "path": "/restaurants/:id/reservation", - "handler": "Restaurant.reservation", - "config": { - "policies": ["is-authenticated", "has-credit-card"] - } - } - ] -} -``` - -- `method` (string): Method or array of methods to hit the route (e.g. `GET`, `POST`, `PUT`, `HEAD`, `DELETE`, `PATCH`). -- `path` (string): URL starting with `/` (e.g. `/restaurants`). -- `handler` (string): Action to execute when the route is hit following this syntax `.`. -- `config` - - `policies` (array): Array of policy names or paths ([see more](/developer-docs/latest/development/backend-customization/policies.md)) - -::: tip -You can exclude the entire `config` object if you do not want the route to be checked by the [Users & Permissions plugin](/developer-docs/latest/plugins/users-permissions.md). -::: - -## Dynamic parameters - -The router used by Strapi allows you to create dynamic routes where you can use parameters and simple regular expressions. These parameters will be exposed in the `ctx.params` object. For more details, please refer to the [PathToRegex](https://github.com/pillarjs/path-to-regexp) documentation. - -```json -{ - "routes": [ - { - "method": "GET", - "path": "/restaurants/:category/:id", - "handler": "Restaurant.findOneByCategory", - "config": { - "policies": [] - } - }, - { - "method": "GET", - "path": "/restaurants/:region(\\d{2}|\\d{3})/:id", // Only match when the first parameter contains 2 or 3 digits. - "handler": "Restaurant.findOneByRegion", - "config": { - "policies": [] - } - } - ] -} -``` - -Example: Route definition with URL params: - -```json -{ - "routes": [ - { - "method": "GET", - "path": "/restaurants/:id", - "handler": "Restaurant.findOne", - "config": { - "policies": [] - } - } - ] -} -``` - -Get the URL param in the controller - -```js -module.exports = { - findOne: async ctx => { - // const id = ctx.params.id; - const { id } = ctx.params; - return id; - }, -}; -```