REST API Conventions

Learn the REST conventions — resources, HTTP verbs, and status codes — and see exactly how Koa's ctx object and @koa/router expose them.

3 min read Level 2/5 #koa#rest#api

What you'll learn

Define REST resources and map CRUD operations to HTTP verbs
Choose the correct HTTP status code for common API responses
Wire a basic resource route in Koa using @koa/router

REST (Representational State Transfer) is an architectural style for designing network APIs. It treats everything the server manages — users, posts, orders — as a resource identified by a URL. HTTP verbs express the operation the client wants to perform on that resource.

Resources and HTTP Verbs

A resource lives at a URL like /articles. The HTTP verb tells the server what to do with it:

Verb	Path	Meaning	Typical Status
GET	/articles	List all articles	200
POST	/articles	Create an article	201
GET	/articles/:id	Fetch one article	200 / 404
PUT	/articles/:id	Replace an article	200
PATCH	/articles/:id	Partially update	200
DELETE	/articles/:id	Remove an article	204

Keeping URLs as nouns (not verbs like /getArticle) is the most important REST convention. Let the HTTP verb do the work.

Mapping to Koa

@koa/router provides .get(), .post(), .put(), .patch(), and .delete() methods that map directly onto this table. Each handler receives the shared ctx object where you read request data and write the response.

import Router from "@koa/router";

const router = new Router({ prefix: "/articles" });

router.get("/", async (ctx) => {
  ctx.body = { articles: [] };          // 200 by default
});

router.post("/", async (ctx) => {
  // body parsed by koa-bodyparser (next lesson)
  ctx.status = 201;
  ctx.body = { id: 1, ...ctx.request.body };
});

router.delete("/:id", async (ctx) => {
  ctx.status = 204;                     // no body on 204
});

Status Code Quick Reference

200 — OK (GET / PUT / PATCH success)
201 — Created (POST success)
204 — No Content (DELETE success, no body)
400 — Bad Request (malformed input)
404 — Not Found (resource missing)
422 — Unprocessable Entity (validation failed)
500 — Internal Server Error (unexpected crash)

Setting ctx.status before assigning ctx.body ensures Koa sends the right code. If you only set ctx.body, Koa defaults to 200.

Up Next

Learn how to parse JSON request bodies with koa-bodyparser so your POST and PATCH handlers can read what the client sent.

Parsing Request Bodies →