docs: add new API route guides + fixes and improvements to existing ones (#8987)

- Add new documentation pages for API route intro, responses, errors, and validation
- General fixes and improvements across existing API route guides

> Note: I didn't work on the guide for additional data validation. Will work on this as part of my next focus on workflows.

www/apps/book/app/advanced-development/api-routes/parameters/page.mdx

@@ -10,7 +10,7 @@ In this chapter, you’ll learn about path, query, and request body parameters.
 
 To create an API route that accepts a path parameter, create a directory within the route file's path whose name is of the format `[param]`.
 
-For example, to create an API Route at the path `/hello-world/{id}`, where `{id}` is a path parameter, create the file `src/api/store/hello-world/[id]/route.ts` with the following content:
+For example, to create an API Route at the path `/hello-world/:id`, where `:id` is a path parameter, create the file `src/api/store/hello-world/[id]/route.ts` with the following content:
 
 export const singlePathHighlights = [
   ["11", "req.params.id", "Access the path parameter `id`"]
@@ -22,7 +22,7 @@ import type {
   MedusaResponse,
 } from "@medusajs/medusa"
 
-export const GET = (
+export const GET = async (
   req: MedusaRequest,
   res: MedusaResponse
 ) => {
@@ -38,7 +38,7 @@ The `MedusaRequest` object has a `params` property. `params` holds the path para
 
 To create an API route that accepts multiple path parameters, create within the file's path multiple directories whose names are of the format `[param]`.
 
-For example, create an API route at `src/api/store/hello-world/[id]/name/[name]/route.ts`:
+For example, to create an API route at `/store/hello-world/:id/name/:name`, create the file `src/api/store/hello-world/[id]/name/[name]/route.ts` with the following content:
 
 export const multiplePathHighlights = [
   ["12", "req.params.id", "Access the path parameter `id`"],
@@ -51,7 +51,7 @@ import type {
   MedusaResponse,
 } from "@medusajs/medusa"
 
-export const GET = (
+export const GET = async (
   req: MedusaRequest,
   res: MedusaResponse
 ) => {
@@ -63,13 +63,13 @@ export const GET = (
 }
 ```
 
-This API route expects two path parameters: `id` and `name`.
+You access the `id` and `name` path parameters using the `req.params` property.
 
 ---
 
 ## Query Parameters
 
-You can access all query parameters in the `query` property of the `MedusaRequest` object.
+You can access all query parameters in the `query` property of the `MedusaRequest` object. `query` is an object of key-value pairs, where the key is a query parameter's name, and the value is its value.
 
 For example:
 
@@ -83,16 +83,18 @@ import type {
   MedusaResponse,
 } from "@medusajs/medusa"
 
-export async function GET(
+export const GET = async (
   req: MedusaRequest,
   res: MedusaResponse
-): Promise<void> {
+) => {
   res.json({
     message: `Hello ${req.query.name}`,
   })
 }
 ```
 
+The value of `req.query.name` is the value passed in `?name=John`, for example.
+
 ---
 
 ## Request Body Parameters
@@ -116,7 +118,7 @@ type HelloWorldReq = {
   name: string
 }
 
-export const POST = (
+export const POST = async (
   req: MedusaRequest<HelloWorldReq>,
   res: MedusaResponse
 ) => {
@@ -128,6 +130,12 @@ export const POST = (
 
 In this example, you use the `name` request body parameter to create the message in the returned response.
 
+<Note title="Tip">
+
+The `MedusaRequest` type accepts a type argument that indicates the type of the request body. This is useful for auto-completion and to avoid typing errors.
+
+</Note>
+
 To test it out, send the following request to your Medusa application:
 
 ```bash apiTesting testApiUrl="http://localhost:9000/store/hello-world" testApiMethod="POST" testBodyParams={{ "name": "" }}