API Routes

## 1. Learning Objectives By the end of this lesson, you will be able to: - Explain what Pages Router API Routes are. - Write a basic `pages/api` handler. - Compare API Routes with App Router Route Handlers. - Recognize API Routes in legacy Next.js projects. Difficulty: Beginner. ## 2. Prerequisites - Pages Router basics. - Route Handlers. - HTTP request and response basics. ## 3. Overview API Routes are the Pages Router way to create backend endpoints in Next.js. They live under `pages/api` and use Node-style request and response objects instead of App Router `route.ts` files. ## 4. Why This Topic Matters New App Router projects should usually use Route Handlers, but many existing Next.js apps still use API Routes. You need to recognize them during maintenance, migrations, and interviews. ## 5. Real-World Analogy API Routes are like the older service window at a building. It still works and many people use it, but new construction may use a newer entrance with different conventions. ## 6. Core Concepts | Concept | Meaning | |---|---| | `pages/api` | Folder for Pages Router API endpoints. | | `NextApiRequest` | Request object used by API Routes. | | `NextApiResponse` | Response object used by API Routes. | | Route Handler | App Router replacement for most new endpoint work. | | Migration | Moving endpoint logic from `pages/api` to `app/api/**/route.ts`. | ## 7. Syntax & API Reference

Equivalent App Router style:

## 8. Visual Diagram

## 9. Live Example - Full Working Code

What just happened? The endpoint handles `POST /api/contact` in the legacy Pages Router style. ## 10. Interactive Playground Try this: - Create a `pages/api/health.ts` endpoint in a Pages Router project. - Convert it to `app/api/health/route.ts`. - Compare request and response types. ## 11. Common Mistakes | Mistake | Why It Happens | Correct Approach | |---|---|---| | Mixing API Route syntax in `route.ts` | Both create endpoints. | Use Web `Request`/`Response` in Route Handlers. | | Adding API Routes to new App Router code by habit | Older tutorials use `pages/api`. | Prefer Route Handlers for new App Router endpoints. | | Skipping method checks | API Route handler receives all methods. | Check `req.method` or split by App Router method exports. | ## 12. Best Practices - Prefer Route Handlers for new App Router projects. - Keep API Routes stable when maintaining legacy apps. - Validate method, body, and authorization. - Migrate endpoints gradually. - Avoid duplicating endpoint logic during migration. ## 13. Browser Compatibility | Feature | Browser Impact | Notes | |---|---|---| | API Route endpoint | Standard HTTP | Any client can call it. | | JSON response | Broad support | Same response shape as other APIs. | | Server-only logic | No browser bundle impact | Runs on server. | ## 14. Interview Questions **Easy:** Where do API Routes live? Answer: Under `pages/api`. **Medium:** What is the App Router replacement for API Routes? Answer: Route Handlers using `app/api/**/route.ts`. **Hard:** Why might a project still use API Routes? Answer: It may be a stable Pages Router or hybrid app where migrating all endpoints at once is unnecessary or risky. ## 15. Debugging Exercise Bug report: "My `app/api/health/route.ts` imports `NextApiRequest` and does not work." Solution That is API Route syntax. Route Handlers use Web `Request` and `Response` objects and named method exports like `GET`. ## 16. Practice Exercises - Easy: Write a `pages/api/health.ts` handler. - Medium: Convert it to an App Router Route Handler. - Hard: Migrate a `POST` API Route with method validation to `route.ts`. ## 17. Scenario-Based Challenge Your codebase has both `pages/api/orders.ts` and `app/api/orders/route.ts`. What should you check? Walkthrough Check for route conflicts, duplicated business logic, inconsistent validation, and which endpoint clients actually call. Consolidate when safe. ## 18. Quick Quiz 1. Are API Routes App Router files? Answer: No. 2. What folder contains API Routes? Answer: `pages/api`. 3. What file creates a Route Handler? Answer: `route.ts`. 4. Should new App Router apps prefer Route Handlers? Answer: Yes. 5. Do API Routes use `NextApiRequest`? Answer: Yes. ## 19. Summary & Key Takeaways - API Routes are the Pages Router endpoint convention. - They live in `pages/api`. - Route Handlers are preferred for App Router projects. - You will still see API Routes in legacy codebases. - Migrate carefully to avoid duplicate endpoint behavior. ## 20. Cheat Sheet | Endpoint Type | Location | Request/Response Style | |---|---|---| | API Route | `pages/api/*.ts` | `NextApiRequest`, `NextApiResponse` | | Route Handler | `app/api/**/route.ts` | Web `Request`, `Response` | | Server Action | Any server action module | Function call/form action | ## 21. Further Reading - Next.js Docs: API Routes. - Next.js Docs: Route Handlers. - Next.js Docs: App Router Migration. ## 22. Next Lesson Preview Chapter 4 is complete. Next, you will move into authentication patterns in Next.js.