Standardizing API Responses

First Steps and Foundations

Welcome 👋 We’re at the very beginning of building a production-grade e-commerce backend with Next.js and PostgreSQL . In this lesson, you won’t connect to a database or implement business logic yet. Instead, you’ll lay down the structural rules that every API endpoint in this project will follow. By the end of this lesson, you’ll understand how our backend defines a strict API contract, how we enforce that contract with reusable response helpers, how to safely parse request bodies, and how routing works in the Next.js App Router. These foundations might seem simple, but they’re what keep large systems consistent and predictable as they grow. Since this is the first lesson in the course path, we’re starting from a clean slate and building our shared language from scratch.

Defining a Strict API Contract

Every backend needs a contract — a shared agreement about what responses look like. If one endpoint returns raw JSON, another returns { result: ... }, and a third returns { data: ... }, your frontend becomes fragile and inconsistent. In this project, that contract lives in src/lib/types/api.ts. This file contains only TypeScript types — no runtime logic — but it defines the structure that every route must follow. Let’s build it piece by piece. First, we define the allowed error codes. TypeScriptexport type ApiErrorCode = | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CONFLICT' | 'DB_ERROR' | 'INTERNAL_ERROR'; ApiErrorCode is a narrow union type. This means only these exact string values are allowed — nothing else. You cannot accidentally return "NotFound" or "bad_request" because TypeScript will reject it. This constraint matters because src/lib/http/response.ts imports and depends on this type. If the contract becomes too loose, you lose compile-time safety. If it’s incorrect, the app won’t compile cleanly. By centralizing error codes here, we ensure the entire backend speaks the same error vocabulary. Next, we define the shape of successful responses. TypeScriptexport interface ApiSuccess<T> { data: T; meta?: { timestamp: string }; } ApiSuccess<T> is generic, which means it can wrap any payload type. Whether you return a product list or an order object, it always lives under data. The meta field is optional, but when present, it contains a timestamp string. This gives us a consistent place for metadata like request timing or debugging context. Wrapping payloads inside data prevents ambiguity. The frontend always knows where the real response lives. Now we define the structure of error responses. TypeScriptexport interface ApiError { error: { code: ApiErrorCode; message: string; details?: unknown }; meta?: { timestamp: string }; } Instead of returning raw error strings, we wrap errors inside an error object. This keeps failure responses clearly separated from success responses. code is machine-readable and restricted to ApiErrorCode, which keeps the system consistent. message is human-readable and intended for display or logging. details is optional and typed as unknown, which allows flexibility for validation errors or debugging context without locking the API into a rigid shape. Finally, we define the full API response type. TypeScriptexport type ApiResponse<T> = ApiSuccess<T> | ApiError; ApiResponse<T> is a union type. It guarantees that every response is either a success envelope or an error envelope — never both and never raw data. This union becomes extremely powerful in TypeScript-aware clients because they can narrow the type based on whether error exists. This type formalizes the contract. Every endpoint must conform to it. At this point, we have defined the language of our backend. Next, we enforce it.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Enforcing the Contract with Response Helpers

Types alone are not enough. Developers can still forget to follow them. That’s why src/lib/http/response.ts centralizes how responses are created.

This file ensures every route returns properly shaped JSON.

Let’s start with a small but important utility: normalizeInit.

TypeScript

function normalizeInit(init?: number | ResponseInit): ResponseInit | undefined {
  if (typeof init === 'number') return { status: init } as ResponseInit;
  return init as ResponseInit | undefined;
}

function normalizeInit(init?: number | ResponseInit): ResponseInit | undefined {
  if (typeof init === 'number') return { status: init } as ResponseInit;
  return init as ResponseInit | undefined;
}

normalizeInit allows route handlers to pass either a numeric status code (like 200) or a full ResponseInit object.
If a number is provided, it converts it into { status: number }. This keeps route handlers clean and concise.
Without this helper, every route would need to manually wrap numeric status codes inside objects.

Now let’s look at the success helper.

TypeScript

export function success<T>(data: T, init?: number | ResponseInit) {
  const body: ApiSuccess<T> = { 
    data, 
    meta: { timestamp: new Date().toISOString() } 
  };
  return NextResponse.json(body, normalizeInit(init));
}

export function success<T>(data: T, init?: number | ResponseInit) {
  const body: ApiSuccess<T> = { 
    data, 
    meta: { timestamp: new Date().toISOString() } 
  };
  return NextResponse.json(body, normalizeInit(init));
}

success<T> constructs a properly shaped ApiSuccess<T> object every time. This ensures the response always has data and a timestamped meta.
The timestamp is generated at the moment of response creation, which can help with debugging or tracing.
NextResponse.json sends the structured object as JSON while respecting the normalized status configuration.
Because this function depends on ApiSuccess<T>, if the contract changes incorrectly, TypeScript will immediately catch inconsistencies.

Now the error helper.

TypeScript

export function error(
  code: ApiErrorCode,
  message: string,
  details?: unknown,
  init?: number | ResponseInit
) {
  const body: ApiError = {
    error: { code, message, details },
    meta: { timestamp: new Date().toISOString() },
  };
  return NextResponse.json(body, normalizeInit(init));
}

export function error(
  code: ApiErrorCode,
  message: string,
  details?: unknown,
  init?: number | ResponseInit
) {
  const body: ApiError = {
    error: { code, message, details },
    meta: { timestamp: new Date().toISOString() },
  };
  return NextResponse.json(body, normalizeInit(init));
}

error ensures all failure responses follow the exact ApiError shape defined earlier.
The code must be one of the allowed ApiErrorCode values, which prevents inconsistent error identifiers.
details is optional and flexible, allowing us to attach structured validation errors later.
Because both success and error include a meta.timestamp, the frontend can rely on consistent metadata regardless of outcome.

By centralizing these helpers, we eliminate duplicated response logic and guarantee contract consistency.

Understanding Routing with a Catch-All Debug Route

To explore how routing works in the App Router, we use a catch-all route located at:

src/app/api/debug/[...slug]/route.ts

The [...slug] syntax means this route captures any number of path segments as an array.

Let’s look at the GET handler.

TypeScript

export async function GET(
  req: NextRequest,
  { params }: { params: Promise<Params> }
) {
  const resolvedParams = await params;
  const query = Object.fromEntries(req.nextUrl.searchParams.entries());
  return success({ method: 'GET', params: resolvedParams, query });
}

export async function GET(
  req: NextRequest,
  { params }: { params: Promise<Params> }
) {
  const resolvedParams = await params;
  const query = Object.fromEntries(req.nextUrl.searchParams.entries());
  return success({ method: 'GET', params: resolvedParams, query });
}

In the App Router, route parameters are provided as a Promise, so we must await params before using them.
resolvedParams.slug contains an array of path segments, such as ["hello", "world"] for /api/debug/hello/world.
We extract query parameters using req.nextUrl.searchParams and convert them into a plain object.
The response is wrapped using success, ensuring it follows our API contract.

Now let’s implement the POST handler using parseJson.

TypeScript

export async function POST(
  req: NextRequest,
  { params }: { params: Promise<Params> }
) {
  const resolvedParams = await params;
  const body = await parseJson(req);

  if (!body.ok) return error(body.code, body.message, undefined, 400);

  return success({ method: 'POST', params: resolvedParams, body: body.value });
}

export async function POST(
  req: NextRequest,
  { params }: { params: Promise<Params> }
) {
  const resolvedParams = await params;
  const body = await parseJson(req);

  if (!body.ok) return error(body.code, body.message, undefined, 400);

  return success({ method: 'POST', params: resolvedParams, body: body.value });
}

We again await params because route params are asynchronous in this setup.
We call parseJson(req) instead of req.json() directly, which protects us from malformed JSON.
If parsing fails, we return error(body.code, body.message, undefined, 400). This ensures the client receives both a proper error envelope and an appropriate HTTP status.
If parsing succeeds, we return a structured success response that includes the method, resolved params, and parsed body. This allows us to verify the entire stack works correctly.

This route is purely for learning and debugging — but it exercises our full contract and response system.

First Steps and Foundations

Defining a Strict API Contract

Join the 1M+ learners on CodeSignal

Enforcing the Contract with Response Helpers

Safe JSON Parsing Without try/catch Everywhere

Understanding Routing with a Catch-All Debug Route

Interacting with the API Through the Playground

Recap