docs: add server routes documentation

docs/content/2.guide/2.features/9.api-routes.md

@@ -1,7 +1,108 @@
 # API Routes
 
-::NeedContribution
-::
+Nuxt will automatically register files in the `/server/api` directory to create API endpoints.
+
+To handle requests, each file should export a default function (an [unjs/h3](https://github.com/unjs/h3) event handler or classic `(req, res) => {}`. The handler can directly return JSON data, a `Promise` or use `event.res.end()` to send response by itself.
+
+Learn more about [h3 methods](https://www.jsdocs.io/package/h3#package-index-functions).
+
+## Route Parameter
+
+For ease of use, routes that are dependent on a parameter can specify the parameter within brackets in the file name `/api/hello/[parameter].ts`.
+
+```ts [/server/api/hello/[name].ts]
+export default defineEventHandler(event => {
+    return `Hello, ${event.context.params.name}!`
+})
+```
+
+## Method Matching
+
+Routes can be suffixed with `.get`, `.post`, `.put`, `.delete` to match a [supported HTTP Method](https://github.com/unjs/nitro/blob/main/src/runtime/virtual/server-handlers.d.ts#L7).
+
+```ts [/server/api/test.post.ts]
+export default defineEventHandler(() => 'Test post handler')
+```
+
+Given the example above, the `test` route will be declared as a `POST` route.
+
+## Catch-all route
+
+A catch all route can be defined by creating a file in the `api` directory with the name `[...].ts`. This route will be triggered for all requests that do not match any other route.
+
+This is useful for special use cases as well as fallback error handling.
+
+```ts [/server/api/[...].ts]
+export default defineEventHandler(event => `Default page`)
+```
+
+## Examples
+
+### Hello World
+
+```ts [/server/api/hello.ts]
+export default defineEventHandler(() => '<h1>Hello World</h1>')
+```
+
+### POST Request
+
+<code-group>
+<code-block label="Basic" active>
+
+```ts [/server/api/hello.ts]
+export default defineEventHandler(async (event) => {
+    const body = await useBody(event) // only for POST | PUT | PATCH | DELETE requests
+
+    return { body }
+})
+```
+
+</code-block>
+<code-block label="Method Matching">
+
+```ts [/server/api/hello.post.ts]
+export default defineEventHandler(() => '<h1>Hello World</h1>')
+```
+
+</code-block>
+</code-group>
+
+### Using Router
+
+```ts [/server/api/hello.ts]
+import { createApp, createRouter } from 'h3'
+
+const app = createApp()
+const router = createRouter()
+
+app.use(router)
+
+router.get('/', () => 'Hello World')
+
+export default app
+```
+
+### Access Request Data
+
+```ts
+export default defineEventHandler(async (event) => {
+  const params = event.context.params;
+  const body = await useBody(event) // only for POST | PUT | PATCH | DELETE requests
+  const cookies = useCookies(event)
+
+  return { params, body, cookies };
+});
+```
+
+### Server Routes
+
+It's now possible to register server handlers without the `/api` prefix, by creating a `server/routes` directory. All handlers in the `routes` directory will be registered as server routes and can be directly requested without the `/api` prefix.
+
+```ts [/server/routes/hello.ts]
+export default defineEventHandler(() => 'Hello World!')
+```
+
+Given the example above, the `/hello` route will be accessible at <http://localhost:3000/hello>.
 
-::ReadMore{link="/guide/directory-structure/server"}
+::ReadMore{link="https://github.com/unjs/nitro#routes-and-api-routes" title="Nitro Routes"}
 ::