-
Notifications
You must be signed in to change notification settings - Fork 1.2k
[v4] Dev docs updates to routes #450
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
0b2747c
Update routes file in backend customization
pwizla f04746d
Improve routes content and wording
pwizla b917212
Fix syntax (JSON → JS)
pwizla 82bca89
Delete routing.md
pwizla ca993b2
Delete backend-customization.md
pwizla 89410c0
Consists in → consists of
pwizla e332d6f
Add missing forward slash in path
pwizla 8b6945d
Add missing forward slash in path
pwizla 76c931a
Add another missing forward slash in path 😅
pwizla 10f5ab6
Add another missing forward slash in path, again 😅
pwizla d7f09a9
Add another missing forward slash 😅 🙈
pwizla 56e4dbe
Remove question comment, no `next` in policies
pwizla 97c8691
Update based on Mégane's feedback
pwizla 81cea30
Merge branch 'dev/next-3' into dev/v4-routes
pwizla File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
166 changes: 166 additions & 0 deletions
166
docs/developer-docs/latest/development/backend-customization/routes.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,166 @@ | ||
--- | ||
title: Routes - Strapi Developer Documentation | ||
description: … | ||
sidebarDepth: 3 | ||
--- | ||
|
||
<!-- TODO: update SEO --> | ||
|
||
# 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. | ||
pwizla marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Once a route exists, reaching it executes some code handled by a controller (see [controllers](/developer-docs/latest/development/backend-customization/controllers.md) documentation). | ||
pwizla marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## 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)). | ||
pwizla marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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.<br>Should follow this syntax: `<controllerName>.<actionName>` | `String` | | ||
| `config`<br><br>_Optional_ | Configuration to handle [policies](policies), [middlewares](middlewares) and [public availability](#public-routes) for the route<br/><br/> | `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', | ||
}, | ||
], | ||
}; | ||
``` | ||
|
||
<br/> | ||
|
||
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 = { | ||
pwizla marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 | ||
pwizla marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
```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: [ | ||
pwizla marked this conversation as resolved.
Show resolved
Hide resolved
|
||
'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). | ||
|
||
<!-- TODO: add link to API token section once documented --> | ||
|
||
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, | ||
}, | ||
}, | ||
], | ||
}; | ||
``` | ||
|
||
*** |
115 changes: 0 additions & 115 deletions
115
docs/developer-docs/latest/development/backend-customization/routing.md
This file was deleted.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.