docs: general updates to documentation pages (#13055)

www/apps/book/app/learn/fundamentals/api-routes/http-methods/page.mdx

@@ -8,7 +8,7 @@ In this chapter, you'll learn about how to add new API routes for each HTTP meth
 
 ## HTTP Method Handler
 
-An API route is created for every HTTP method you export a handler function for in a route file.
+An API route is created for every HTTP method you export a handler function for in a `route.ts` or `route.js` file.
 
 Allowed HTTP methods are: `GET`, `POST`, `DELETE`, `PUT`, `PATCH`, `OPTIONS`, and `HEAD`.
 
@@ -39,7 +39,7 @@ export const POST = async (
 }
 ```
 
-This adds two API Routes:
+This file adds two API Routes:
 
-- A `GET` route at `http://localhost:9000/hello-world`.
-- A `POST` route at `http://localhost:9000/hello-world`.
+- A `GET` API route at `http://localhost:9000/hello-world`.
+- A `POST` API route at `http://localhost:9000/hello-world`.

www/apps/book/app/learn/fundamentals/api-routes/page.mdx

@@ -4,25 +4,25 @@ export const metadata = {
 
 # {metadata.title}
 
-In this chapter, you’ll learn what API Routes are and how to create them.
+In this chapter, you’ll learn what API routes are and how to create them.
 
 ## What is an API Route?
 
-An API Route is an endpoint. It exposes commerce features to external applications, such as storefronts, the admin dashboard, or third-party systems.
+An API route is a REST endpoint that exposes commerce features to external applications, such as storefronts, the admin dashboard, or third-party systems.
 
-The Medusa core application provides a set of admin and store API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
+The Medusa core application provides a set of [admin](!api!/admin) and [store](!api!/store) API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
 
 ---
 
 ## How to Create an API Route?
 
-An API Route is created in a TypeScript or JavaScript file under the `src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`. 
+You can create an API route in a TypeScript or JavaScript file under the `src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`. 
 
 ![Example of API route in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732808645/Medusa%20Book/route-dir-overview_dqgzmk.jpg)
 
-Each file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
+Each file exports API route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
 
-For example, to create a `GET` API Route at `/hello-world`, create the file `src/api/hello-world/route.ts` with the following content:
+For example, to create a `GET` API route at `/hello-world`, create the file `src/api/hello-world/route.ts` with the following content:
 
 ```ts title="src/api/hello-world/route.ts"
 import type {
@@ -40,7 +40,7 @@ export const GET = (
 }
 ```
 
-### Test API Route
+### Test the API Route
 
 To test the API route above, start the Medusa application:
 
@@ -48,18 +48,22 @@ To test the API route above, start the Medusa application:
 npm run dev
 ```
 
-Then, send a `GET` request to the `/hello-world` API Route:
+Then, send a `GET` request to the `/hello-world` API route:
 
 ```bash
 curl http://localhost:9000/hello-world
 ```
 
+You should receive the following response:
+
+```json
+{
+  "message": "[GET] Hello world!"
+}
+```
+
 ---
 
-## When to Use API Routes
+## Next Chapters: Learn More About API Routes
 
-<Note title="Use API routes when" type="success">
-
-You're exposing custom functionality to be used by a storefront, admin dashboard, or any external application.
-
-</Note>
+Follow the next chapters to learn about the different HTTP methods you can use in API routes, parameters and validation, protecting routes, and more.

www/apps/book/app/learn/fundamentals/api-routes/responses/page.mdx

@@ -8,7 +8,7 @@ In this chapter, you'll learn how to send a response in your API route.
 
 ## Send a JSON Response
 
-To send a JSON response, use the `json` method of the `MedusaResponse` object passed as the second parameter of your API route handler.
+To send a JSON response, use the `json` method of the `MedusaResponse` object that is passed as the second parameter of your API route handler.
 
 For example:
 
@@ -78,7 +78,7 @@ export const streamHighlights = [
   ["7", "writeHead", "Set the response's headers."],
   ["7", "200", "Set the status code."],
   ["8", `"Content-Type"`, "Set the response's content type."],
-  ["13", "interval", "Simulate stream data using an interval"],
+  ["13", "interval", "Simulate stream data using an interval."],
   ["14", "write", "Write stream data."],
   ["17", "on", "Stop the stream when the request is terminated."]
 ]
@@ -109,10 +109,10 @@ export const GET = async (
 
 The `writeHead` method accepts two parameters:
 
-1. The first one is the response's status code.
-2. The second is an object of key-value pairs to set the headers of the response.
+1. The first parameter is the response's status code.
+2. The second parameter is an object of key-value pairs to set the response headers.
 
-This API route opens a stream by setting the `Content-Type` in the header to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
+This API route opens a stream by setting the `Content-Type` to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
 
 ---