From 4adab3d4b01dcb7f0742c57a4399ba2cbe618796 Mon Sep 17 00:00:00 2001 From: swyx Date: Thu, 2 Apr 2020 17:05:01 +0800 Subject: [PATCH] [docs] document how root routes coexist with dynamic api routes (#11591) * document how root routes coexist with dynamic api routes document how root routes coexist with dynamic api routes - related to https://github.com/zeit/next.js/issues/11542 * Update dynamic-api-routes.md * Update dynamic-api-routes.md * Run prettier Co-authored-by: Tim Neutkens --- docs/api-routes/dynamic-api-routes.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/api-routes/dynamic-api-routes.md b/docs/api-routes/dynamic-api-routes.md index fe700be588a87..e353f06aff497 100644 --- a/docs/api-routes/dynamic-api-routes.md +++ b/docs/api-routes/dynamic-api-routes.md @@ -20,6 +20,25 @@ export default (req, res) => { Now, a request to `/api/post/abc` will respond with the text: `Post: abc`. +### Index routes and Dynamic API routes + +A very common RESTful pattern is to set up routes like this: + +- `GET api/posts/` - gets a list of posts, probably paginated +- `GET api/posts/12345` - gets post id 12345 + +We can model this in two ways: + +- Option 1: + - `/api/posts.js` + - `/api/posts/[postId].js` +- Option 2: + + - `/api/posts/index.js` + - `/api/posts/[postId].js` + +Both are equivalent. A third option of only using `/api/posts/[postId].js` is not valid because Dynamic Routes (including Catch-all routes - see below) do not have an `undefined` state and `GET api/posts/` will not match `/api/posts/[postId].js` under any circumstances. + ### Catch all API routes API Routes can be extended to catch all paths by adding three dots (`...`) inside the brackets. For example: