ReviseAlgo Logo

Data Fetching

API Routes

Learn legacy Pages Router API Routes, how they compare with App Router Route Handlers, and when you will still encounter them.

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

    ConceptMeaning
    pages/apiFolder for Pages Router API endpoints.
    NextApiRequestRequest object used by API Routes.
    NextApiResponseResponse object used by API Routes.
    Route HandlerApp Router replacement for most new endpoint work.
    MigrationMoving 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

    MistakeWhy It HappensCorrect Approach
    Mixing API Route syntax in route.tsBoth create endpoints.Use Web Request/Response in Route Handlers.
    Adding API Routes to new App Router code by habitOlder tutorials use pages/api.Prefer Route Handlers for new App Router endpoints.
    Skipping method checksAPI 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

    FeatureBrowser ImpactNotes
    API Route endpointStandard HTTPAny client can call it.
    JSON responseBroad supportSame response shape as other APIs.
    Server-only logicNo browser bundle impactRuns 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 TypeLocationRequest/Response Style
    API Routepages/api/*.tsNextApiRequest, NextApiResponse
    Route Handlerapp/api/**/route.tsWeb Request, Response
    Server ActionAny server action moduleFunction 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.