Create Your Own API

Before You Study (5 mins)

Lesson focus: Until now, you've called other people's APIs (Lesson 09: weather, quotes, LLMs). Today you flip the relationship and become the API provider. Your backend will expose a real REST API for a Snake-game leaderboard — GET to read scores, POST to add one, DELETE to clear them — with proper request validation, error handling, and the conventions every professional API follows. By the end, your frontend talks to your backend over an interface you designed and own.

What you should have ready:

• Lesson 12's backend/ directory with Express, CORS, and the /api/health route working
• nodemon running so the server hot-reloads as you edit
• A REST client for testing — your terminal curl is fine, Insomnia or Bruno are free GUIs
• About 60 minutes
• Patience for debugging — half of API work is fixing the 400-status response that just came back

The Concept

A REST API is a way of designing HTTP endpoints around a small, consistent vocabulary. The word "REST" stands for Representational State Transfer — but the practical meaning today is: resources have URLs, and HTTP verbs do operations on those resources. That's the entire idea.

The vocabulary you saw in Lesson 09 from the consumer side, now applied as a designer:

The same path with different verbs does different things. This is RESTful design's core elegance: a small, predictable surface that any developer can navigate without docs.

A real API has more than just routes. It has a request-handling pipeline that is the same shape on every server you'll ever build:

HTTP request arrives
      │
      ▼
1. Parse body / query params (express.json())
      │
      ▼
2. Validate input (is name a non-empty string? is score a number?)
      │
      ▼
3. Authenticate (who is the caller? do they have a valid token?)   [later lessons]
      │
      ▼
4. Authorize (are they allowed to do THIS action?)                 [later lessons]
      │
      ▼
5. Execute business logic (compute, query DB, call other services)
      │
      ▼
6. Format response (set status code, return JSON)
      │
      ▼
HTTP response sent

This pipeline is implemented in Express through middleware — small functions that run in order, each one either passing control to the next (next()) or short-circuiting with a response. Authentication, validation, logging, error handling — they're all middleware. Once this clicks, every Express server feels like the same shape.

A few conventions every well-designed API follows:

• Use the right verb. GET doesn't change state. POST creates. DELETE removes. Mixing them up confuses everyone, including future-you.
• Return the right status code. 200 OK for read, 201 Created for write, 204 No Content for delete, 400 Bad Request for validation failures, 404 Not Found for missing resources, 500 Internal Server Error for crashes. The status code is the API speaking to you in its own language; respect it.
• Return JSON, always. Even errors ({ "error": "name is required" }). Never plain text or HTML.
• Validate everything. A POST /scores with score: "🐍" instead of a number should fail at validation, not at the database.
• Be idempotent where you can. A PUT /scores/42 with the same body should produce the same end state on every call. POST is the exception.

Today we'll build a toy in-memory leaderboard — scores stored in a JavaScript array, lost on server restart. Lesson 14 replaces the array with a real SQLite database. The route handlers and the API design stay identical; only the storage changes. This is a deliberate decoupling: API surface is the contract, storage is the implementation.

The companion article for the consumer side of this lesson is What is an API and How Do APIs Actually Work — which now reads differently because you're about to design your own.

Quick Concepts

What We Will Build

By the end of this lesson, you will have done these specific things:

1. Set up an in-memory store in server.js — a simple JavaScript array we can read and write to:
   javascript

   Copy

   let scores = []           // [{ id, name, score, createdAt }]
   let nextId = 1
   

2. Built GET /api/scores — returns the array, sorted by score descending, optionally paginated via ?limit=10:
   javascript

   Copy

   app.get('/api/scores', (req, res) => {
     const limit = Math.min(Number(req.query.limit) || 10, 100)
     const sorted = [...scores].sort((a, b) => b.score - a.score).slice(0, limit)
     res.json({ scores: sorted, count: sorted.length, total: scores.length })
   })
   

3. Built POST /api/scores — accepts { name, score }, validates them, creates a new entry, returns it with a 201 Created:
   javascript

   Copy

   app.post('/api/scores', (req, res) => {
     const { name, score } = req.body
     if (typeof name !== 'string' || name.trim().length < 1 || name.length > 30) {
       return res.status(400).json({ error: 'name must be a 1-30 char string' })
     }
     if (typeof score !== 'number' || score < 0 || !Number.isFinite(score)) {
       return res.status(400).json({ error: 'score must be a non-negative number' })
     }
     const entry = { id: nextId++, name: name.trim(), score, createdAt: new Date().toISOString() }
     scores.push(entry)
     res.status(201).json(entry)
   })
   

4. Built GET /api/scores/:id — returns one specific score by ID; 404 Not Found if it doesn't exist.
5. Built DELETE /api/scores/:id — removes a score; 204 No Content on success.
6. Tested every endpoint with curl — the discipline of testing your own API from the terminal builds the muscle every senior backend engineer has:
   bash

   Copy

   curl -s http://localhost:3001/api/scores | jq .
   curl -s -X POST http://localhost:3001/api/scores \
     -H 'Content-Type: application/json' \
     -d '{"name":"Divyanshu","score":1500}' | jq .
   

7. Triggered every error path on purpose — sent a missing name (expect 400), sent an invalid score (expect 400), fetched a non-existent ID (expect 404), so you've seen the failure modes of your own API.
8. Wired the frontend — your Snake game now calls POST /api/scores on game-over and GET /api/scores on game-start. The leaderboard appears on screen.
9. Added one global error-handler middleware at the bottom of your server so any uncaught error returns a clean 500 Internal Server Error JSON instead of an HTML stack trace:
   javascript

   Copy

   app.use((err, req, res, next) => {
     console.error(err)
     res.status(500).json({ error: 'Internal server error' })
   })
   

Step 9 is what separates a real API from a hello-world demo. In production, something will throw; the question is what the user sees when it does.

Think About

Before studying, consider:

1. If you accept any payload POST /api/scores sends — including { "score": 999999999 } from a malicious client — your leaderboard fills with garbage in 60 seconds. Where does the rule "scores must be plausible" belong? (Hint: not just on the frontend. Backend validation is non-negotiable.)
2. The leaderboard you build today loses all data on server restart. That's fine for development. What changes the moment you put this in production with real users? (Hint: the storage layer becomes the most important part of the system. Lesson 14 builds it.)

By the End

After this lesson, you'll:

• Have a working CRUD API for scores (Create, Read one, Read many, Delete)
• Know the right HTTP verb for each operation
• Know the right status code for each outcome (200 / 201 / 204 / 400 / 404 / 500)
• Validate every input before touching state
• Have a global error-handling middleware
• Test your own API from curl and from your frontend
• Be ready for Lesson 14 — replacing the in-memory array with a real database

You are the chef now. The world places orders. 👨‍🍳

What We Learned

• REST is a small vocabulary: resources have URLs, HTTP verbs operate on them. GET /scores reads, POST /scores creates, DELETE /scores/:id removes. Once you internalize this, the design of every API becomes legible.
• Express's request-handling pipeline is middleware — small functions running in order, each one either passing control onward (next()) or short-circuiting with a response. Authentication, validation, logging, error handling are all middleware.
• Validation is non-negotiable. Every input that crosses the network boundary is untrusted until proven otherwise. typeof, range checks, length limits — fast, simple, and the difference between "production-ready" and "demo."
• Status codes are the protocol. Use 201 Created for successful POST, 204 No Content for successful DELETE, 400 Bad Request for malformed input, 404 Not Found for missing resources. Returning 200 OK for everything is a beginner tell.
• Error-handling middleware is the safety net that converts any uncaught throw into a clean JSON 500 response. Every Express server you ever write should have one at the bottom of the route stack.
• In-memory storage is fine for development, but disappears on restart. Lesson 14 replaces the JavaScript array with a real database; the API surface stays identical.

Commands We Used

# Read all scores
curl -s http://localhost:3001/api/scores | jq .

# Read with a limit
curl -s "http://localhost:3001/api/scores?limit=5" | jq .

# Create a score
curl -s -X POST http://localhost:3001/api/scores \
  -H 'Content-Type: application/json' \
  -d '{"name":"Divyanshu","score":1500}' | jq .

# Read a specific score by ID
curl -s http://localhost:3001/api/scores/1 | jq .

# Delete a score
curl -i -X DELETE http://localhost:3001/api/scores/1

# Trigger a validation error on purpose
curl -i -X POST http://localhost:3001/api/scores \
  -H 'Content-Type: application/json' \
  -d '{"name":"","score":-5}'
# → HTTP/1.1 400 Bad Request

# Trigger a not-found on purpose
curl -i http://localhost:3001/api/scores/9999
# → HTTP/1.1 404 Not Found

The complete API surface for server.js:

import 'dotenv/config'
import express from 'express'
import cors from 'cors'

const app = express()
app.use(cors())
app.use(express.json())

// In-memory store (replaced with SQLite in Lesson 14)
let scores = []
let nextId = 1

// ── Read many ─────────────────────────────────
app.get('/api/scores', (req, res) => {
  const limit = Math.min(Number(req.query.limit) || 10, 100)
  const sorted = [...scores]
    .sort((a, b) => b.score - a.score)
    .slice(0, limit)
  res.json({ scores: sorted, count: sorted.length, total: scores.length })
})

// ── Read one ──────────────────────────────────
app.get('/api/scores/:id', (req, res) => {
  const entry = scores.find((s) => s.id === Number(req.params.id))
  if (!entry) return res.status(404).json({ error: 'Score not found' })
  res.json(entry)
})

// ── Create ────────────────────────────────────
app.post('/api/scores', (req, res) => {
  const { name, score } = req.body

  if (typeof name !== 'string' || name.trim().length < 1 || name.length > 30) {
    return res.status(400).json({ error: 'name must be a 1-30 char string' })
  }
  if (typeof score !== 'number' || score < 0 || !Number.isFinite(score)) {
    return res.status(400).json({ error: 'score must be a non-negative number' })
  }

  const entry = {
    id: nextId++,
    name: name.trim(),
    score,
    createdAt: new Date().toISOString()
  }
  scores.push(entry)
  res.status(201).json(entry)
})

// ── Delete ────────────────────────────────────
app.delete('/api/scores/:id', (req, res) => {
  const id = Number(req.params.id)
  const before = scores.length
  scores = scores.filter((s) => s.id !== id)
  if (scores.length === before) {
    return res.status(404).json({ error: 'Score not found' })
  }
  res.status(204).send()
})

// ── Global error handler — must be last ──────
app.use((err, req, res, next) => {
  console.error('Unhandled error:', err)
  res.status(500).json({ error: 'Internal server error' })
})

const PORT = process.env.PORT || 3001
app.listen(PORT, () => console.log(`API on http://localhost:${PORT}`))

Why It Matters

The skill of designing a clean API is what makes someone hireable in backend or full-stack engineering. The actual code — Express handlers, middleware, validation — is mechanical. The judgment is in what to expose, in what shape, with what error contract. Senior engineers spend more time thinking about API surfaces than writing the implementation behind them, because the surface is the contract that survives across versions, refactors, and team changes.

The deeper insight: APIs you design today will be called by code you haven't written yet, by people you haven't met yet. Maybe it's a future colleague writing a mobile app. Maybe it's an integration partner. Maybe it's an AI agent in 2027. A good API is the one that someone can use without reading more than a paragraph of docs because the conventions are predictable.

Real-world considerations this lesson glossed over:

• Authentication and authorization — who is allowed to call which endpoint? Sessions, JWTs, OAuth 2.0. Most production APIs require an auth header on every request.
• Pagination — ?limit= is the simplest version; cursor-based pagination handles larger datasets without skip/limit performance issues.
• Versioning — GET /api/v1/scores vs GET /api/v2/scores. A real API has breaking changes over years; versioning is how you support both old and new clients simultaneously.
• Rate limiting — express-rate-limit is the simplest install; production uses Redis-backed limiters that work across multiple server instances.
• Schema validation libraries — zod, joi, valibot. Replace your hand-rolled typeof checks with declarative schemas that produce structured error messages.
• OpenAPI specifications — machine-readable API contracts (openapi.yaml) that auto-generate client SDKs in any language.

The companion article What is an API and How Do APIs Actually Work covered all of this from the consumer perspective. Today's lesson made you the provider. Re-read the article tonight; the same content reads differently when you've been on both sides.

Checklist

• My server has GET /api/scores, POST /api/scores, GET /api/scores/:id, DELETE /api/scores/:id
• POST validates that name is a 1-30 char string and score is a non-negative number
• GET supports ?limit= and returns the most-recent or highest scores first
• Each endpoint returns the correct status code (200 / 201 / 204 / 400 / 404)
• I have a global error-handling middleware that returns 500 JSON on uncaught exceptions
• My Snake game calls POST /api/scores on game-over and renders the leaderboard from GET /api/scores
• I tested every endpoint and every error path with curl

Quick Quiz

Q1: Which framework makes building HTTP APIs in Node.js easy?

• A) Hapi.js — also a Node framework, but more opinionated and heavier
• B) Express.js — the most widely-used minimalist HTTP framework ✓
• C) Sequelize — that's an ORM, not an HTTP framework

Q2: What HTTP method should you use to create a new resource?

• A) GET
• B) POST ✓
• C) DELETE

Q3: What is req.body?

• A) The HTTP body of the response
• B) The parsed JSON body of an incoming POST/PUT/PATCH request ✓
• C) A backup of the request

Q4: What status code should a successful POST that creates a resource return?

• A) 200 OK
• B) 201 Created ✓
• C) 204 No Content

Q5: Why do you need a global error-handling middleware?

• A) Because Express doesn't support throws
• B) To convert any uncaught exception into a clean JSON 500 response, instead of an HTML stack trace ✓
• C) Because the linter requires it

Bonus Challenge

Add request logging — a tiny middleware that prints every incoming request with method, path, status code, and elapsed time:

app.use((req, res, next) => {
  const start = Date.now()
  res.on('finish', () => {
    console.log(`${req.method} ${req.path} → ${res.statusCode} (${Date.now() - start}ms)`)
  })
  next()
})

Add this before your routes. Now every request leaves a trace in your terminal:

POST /api/scores → 201 (3ms)
GET /api/scores → 200 (1ms)
DELETE /api/scores/9999 → 404 (1ms)

This is the simplest version of "observability" — the discipline of making your server's behavior visible. Production systems use structured loggers, log aggregators, and tracing — but the seed is this 6-line middleware.

Next Lesson

Lesson 14: Databases — Store Data Permanently with SQLite

You'll learn: Your API works, but every server restart wipes the leaderboard. Tomorrow we replace the in-memory array with a real database file. The API stays identical; only the storage swaps. This is the boundary every full-stack engineer crosses, and once you cross it, your projects start surviving real use.

Today you served. Tomorrow you remember. 🌐