Back to path
SmallWeekend build ~6h· 4 milestones

Design and build a well-documented API

Most "build an API" submissions work but would never pass code review. You build one that would: validated, paginated, authenticated, documented, and tested.

API designInput validationPaginationAuthOpenAPI/schemaTestingStructured loggingCost awareness
Build this freeBrowse all projectsNo credit card. Already a member?

What you'll build

A REST (or GraphQL) API with input validation, pagination, authentication, an OpenAPI/schema spec, and a test suite covering the contract.

See how we teach, before you sign up

You don't just get code dumped on you. Every starter file and every solution is explained line-by-line, in plain English. Here's one real file from this project:

src/error.tsts
import type { Response } from 'express';

// Every error response in the API has exactly this shape.
export interface ApiError {
  error: {
    code: string;        // machine-readable, e.g. "validation_error"
    message: string;     // human-readable
    details?: unknown;   // optional field-level info
  };
}

export function sendError(
  res: Response,
  status: number,
  code: string,
  message: string,
  details?: unknown,
): void {
  const body: ApiError = { error: { code, message, ...(details ? { details } : {}) } };
  res.status(status).json(body);
}

Reading this file

  • interface ApiErrorDefines one fixed JSON shape for every error so API consumers can parse failures the same way every time.
  • code: stringA machine-readable error code (like "validation_error") lets client code branch on the kind of failure, not the wording.
  • function sendError(A single helper for all error responses, so you never accidentally invent a different error format per endpoint.
  • res.status(status).json(body)Sets the correct HTTP status code AND the consistent body together, the two halves of a proper error response.

One error shape used everywhere, the thing reviewers check first.

That's 1 of 8 explained code blocks in this single project.

The build, milestone by milestone

  1. 1

    Design the contract

    5 guided steps

    An API is a contract other people build against. Designing it first prevents the inconsistent status codes and ad-hoc error shapes that make an API painful to consume.

  2. 2

    Implement with guardrails

    5 guided steps

    Unvalidated input is the source of most security and data-integrity bugs. Server-side validation and auth are non-negotiable, the client can never be trusted.

  3. 3

    Document & test

    5 guided steps

    Docs drift from reality unless tests enforce the contract. Tests that assert the spec are what let you change the implementation without breaking consumers.

  4. 4

    Make it observable & cost-aware

    5 guided steps

    An API nobody can see into is undebuggable in production, and one nobody has costed gets a surprise bill. A thin operability pass is what separates a toy from something you would deploy.

What's inside when you start

4 starter files, ready to clone
4 guided milestones
4 full reference solutions
8 code blocks explained line-by-line
4 "is it working?" checks
4 interview questions it prepares you for

You'll walk away with

A running API with a published OpenAPI/GraphQL schema and interactive docs
A test suite covering happy paths and error cases
A README with run instructions, example requests, and a cost-per-1M-requests estimate
A health endpoint plus structured per-request logs with request IDs

This is portfolio-grade. Build it free.

Sign up to unlock every milestone step-by-step, the code skeletons, full reference solutions, and checkable tasks, with your progress saved as you build.

Start building