HTTP methods

Safe means the request does not change anything on the server. Idempotent means sending it twice has the same effect as sending it once, so a client or proxy may retry it after a timeout (APIs, API design).

Status codes worth knowing

The first digit tells the client what to do: 2xx done, 3xx look elsewhere, 4xx the client must change the request, 5xx the server failed and a retry may help. Never return 200 with an error inside the body (APIs).

Headers you will set or read

Header names are case-insensitive. Custom headers no longer need an X- prefix (APIs).

Resource design rules

• Nouns in the path, plural collections: GET /stores/S-014/orders, GET /orders/ord_81f2. The method is the verb.
• Actions that are not simple CRUD get a sub-resource: POST /orders/ord_81f2/cancel.
• Nest only one level, for ownership. Filter with query parameters: GET /orders?storeId=S-014&status=packed.
• Money in integer cents with a currency: { "totalCents": 1299, "currency": "USD" }. Never floats.
• Times in UTC ISO 8601: "2026-03-01T09:30:00Z". Dates without time as "2026-03-01".
• Ids are opaque strings to clients. Do not expose auto-increment ids if guessing them leaks volume or data.
• Pick one casing for JSON fields (camelCase is common in Node) and keep it everywhere.
• Return the created or updated resource so the client does not need a second call.

See API design and Data and API.

Pagination: offset or cursor

Always paginate lists and cap the page size (for example 100). The Partner app's order history once returned every order a shop ever placed in one response (API design, Everyday SQL).

One error format everywhere

Clients should handle every error the same way. RFC 9457 "Problem Details" (which replaced RFC 7807) is a ready-made shape with the media type application/problem+json. Keep a stable machine-readable code, a human message, and a request id the support team can search for (API design, Tests and docs).

{
  "type": "https://api.mangrove.example/errors/slot-full",
  "title": "Delivery slot is full",
  "status": 409,
  "detail": "The 18:00-19:00 slot at store S-014 has no capacity left.",
  "code": "SLOT_FULL",
  "requestId": "req_7Hq2c",
  "errors": [{ "field": "slotId", "message": "Choose another slot" }]
}

Auth: which one?

Authentication proves who is calling; authorization decides what they may do. Check authorization on every request, on the server, for the specific record (Auth and limits, Access control, Auth and sessions).

JWT rules

• A JWT is signed, not encrypted: anyone can read its payload. Never put secrets or personal data in it.
• Verify the signature with a fixed, allowed algorithm list. Reject alg: none.
• Check exp, iss and aud on every request.
• Keep access tokens short (minutes); you cannot easily revoke a JWT before it expires.
• Load roles and store access from the database for sensitive actions instead of trusting old claims.

Rate limits, idempotency and retries

Rate limit per API key or user, return 429 with Retry-After. Clients retry only idempotent requests, or POSTs with an idempotency key, with exponential backoff and jitter and a retry cap (Rate limiting, Timeouts and retries, Jobs and retries).

Webhooks

Receiving them (a payment provider tells Mangrove a payment succeeded) and sending them (Mangrove tells the Partner app an order shipped) follow the same rules (No overselling, Jobs and retries).

• Verify the signature (usually an HMAC of the raw body with a shared secret) with a constant-time compare, and reject old timestamps to stop replays.
• Answer 2xx fast, then do the work in a queue. Slow handlers cause the sender to time out and retry.
• Expect duplicates and out-of-order delivery: store the event id with a unique constraint, and check state before acting.
• When sending: retry with backoff for hours, sign every request, include an event id and type, and give receivers a way to replay.
• Run a reconciler that asks the provider about anything still pending; webhooks get lost.

Versioning and change

Mobile apps stay installed for months, so the Mangrove app version from last year still calls today's API (API design, Safe migrations).

NestJS and Prisma snippets

The Mangrove platform runs NestJS on Node with Prisma for Postgres. A controller with validation, a guard and a scoped query (NestJS service, Prisma data, Auth and limits):

// main.ts: reject unknown fields and convert types for every DTO
app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));

// create-order.dto.ts
export class CreateOrderDto {
  @IsString() storeId: string;
  @IsArray() @ValidateNested({ each: true }) @Type(() => LineDto) lines: LineDto[];
}

// orders.controller.ts
@Controller('orders')
@UseGuards(AuthGuard)
export class OrdersController {
  constructor(private readonly orders: OrdersService, private readonly prisma: PrismaService) {}

  @Post()
  @HttpCode(201)
  create(@Body() dto: CreateOrderDto, @Headers('idempotency-key') key: string, @Req() req) {
    return this.orders.create(req.user, dto, key);
  }

  @Get(':id')
  async findOne(@Param('id') id: string, @Req() req) {
    const order = await this.prisma.order.findFirst({
      where: { id, storeId: { in: req.user.storeIds } },   // scope by the caller, not just by id
      select: { id: true, status: true, totalCents: true }, // never return whole rows by default
    });
    if (!order) throw new NotFoundException();
    return order;
  }
}

Testing and documenting

Test at the HTTP level: send a real request to the app with a test database, and assert on status, body and side effects (Tests and docs, Unit and API tests, API testing).

• For every endpoint test: happy path, validation error (400 or 422), no token (401), wrong store (403 or 404), not found, duplicate (409), and a retry with the same idempotency key.
• NestJS with Supertest: await request(app.getHttpServer()).post('/orders').set('Authorization', `Bearer ${token}`).send(body).expect(201).
• Generate an OpenAPI document from code (@nestjs/swagger) and publish it; generate client types from it.
• Contract tests catch the day the Partner app and the API stop agreeing, before users do (Contract tests).
• Load test the endpoints that face festival peaks, such as checkout and slot booking (Load testing).
• Log one structured line per request: method, route, status, duration, user id and request id. Never log tokens, passwords or full card numbers.

Security checklist for every endpoint

• Who may call this, and for which records? Check ownership in the query, not only in the UI (Access control).
• Validate and allow-list input; parameterize every query (Injection).
• Return only the fields the caller needs; never return password hashes or internal notes.
• Set body size limits and timeouts; rate limit login, OTP and search (Auth and limits).
• Secrets come from the environment or a secret manager, never from the repository (Security).
• Check the OWASP API Security Top 10 before launch.

Glossary

Plain definitions of the API terms used across the backend courses.

Endpoint

One method plus path that the API answers, such as POST /orders. APIs

REST

A style of API built from resources addressed by URLs and changed with standard HTTP methods. API design

Resource

A thing the API exposes, such as an order or a store, with its own URL. API design

Idempotent

Doing it twice has the same effect as doing it once. Jobs and retries

Idempotency key

A unique value sent with a request so the server can recognise a retry and return the first result. Jobs and retries

DTO (data transfer object)

A class describing the shape of a request or response, used for validation. NestJS service

Guard

NestJS code that runs before a route handler and decides whether the request may continue. Auth and limits

Pipe

NestJS code that validates or transforms input before the handler sees it. NestJS service

ORM

A library that maps database rows to objects in code, such as Prisma. Prisma data

Migration

A versioned script that changes the database schema, run in order in every environment. Safe migrations

Cursor pagination

Paging by "give me items after this one" instead of a page number; stable and fast. API design

ETag

A version tag for a resource, used for conditional GETs and safe concurrent updates. Caching

CORS

Browser rules that decide which other web origins may call your API from JavaScript. Auth and sessions

CSRF

An attack where another site makes the user's browser send a request with their cookies; blocked with SameSite cookies and tokens. Auth and sessions

Session

Server-side record of a signed-in user, referenced by a random id in a cookie. Auth and sessions

JWT (JSON Web Token)

A signed, base64url-encoded set of claims used as a self-contained access token. Auth and limits

OAuth 2.0

A framework for letting an app get limited access tokens for a user or service. Auth and limits

PKCE

Proof Key for Code Exchange: a one-time secret that stops a stolen authorization code being used by another app. Auth and limits

OpenID Connect

An identity layer on OAuth 2.0 that adds an ID token saying who the user is. Identity

Refresh token

A long-lived token used only to get new short-lived access tokens. Auth and limits

Rate limit

A cap on requests per client per period, answered with 429 when exceeded. Rate limiting

Webhook

An HTTP call one system makes to another when something happens. No overselling

HMAC signature

A hash of the message with a shared secret, proving it came from the sender and was not changed. No overselling

OpenAPI

A standard machine-readable description of an HTTP API, used for docs, client generation and tests. Tests and docs

Contract test

A test that checks a provider still meets what its consumers expect. Contract tests

Problem Details

RFC 9457's standard JSON shape for HTTP API errors. API design

Courses on Kolom

• Building APIs with Node.js: design, NestJS, Prisma, auth, jobs, tests and docs for Mangrove's order API.
• How the Web Works: what happens between the phone and the server, and API basics.
• Application Security for Developers: access control, injection and sessions done right.
• Scaling Building Blocks: caching, queues and rate limiting behind the API.
• Distributed Systems: timeouts, retries, outbox and sagas when one API calls another.

What to read next

• MDN Web Docs on HTTP at developer.mozilla.org. The clearest reference for methods, status codes, headers, caching and CORS.
• RFC 9110, HTTP Semantics at rfc-editor.org. The source for what each method and status code means.
• OWASP API Security Top 10 at owasp.org. The most common ways APIs leak data.
• The OpenAPI Specification at spec.openapis.org.
• The NestJS documentation at docs.nestjs.com and the Prisma documentation at prisma.io/docs.