Skip to content

MISC — Miscellaneous Technical Notes

Last reviewed: 2026-09-17

Purpose: Catch-all reference for cross-cutting technical topics that do not belong to a single technology folder — currently HTTP API design conventions and API authentication.

Overview

This article collects notes that apply across the rest of the knowledge base: how to shape an HTTP API, and how to protect it.

Topics Covered

  • REST resource modelling and HTTP verb semantics
  • Versioning, pagination, filtering and error envelopes
  • Idempotency, retries and rate limiting
  • API authentication methods: API keys, JWT, OAuth 2.0, Basic auth, mTLS
  • Choosing an authentication method per client type

General API Concepts Relevant to Multiple Topics

REST API Design Principles

  • Resources — Everything is a resource (users, orders, products)
  • HTTP verbs — GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
  • Statelessness — Each request contains all needed information
  • Naming — Plural nouns, lowercase, hyphens: /api/v1/users
  • Pagination — ?page=1&limit=50 or cursor-based
  • Error handling — Consistent error response structure

Request / Response Conventions

Concern Convention
Versioning Path prefix (/api/v1/) or Accept header negotiation
Filtering Query parameters, e.g. ?status=active&created_after=2026-01-01
Sorting ?sort=-created_at (leading - for descending)
Idempotency PUT/DELETE are idempotent; use an Idempotency-Key header for retried POSTs
Errors One envelope: {"error": {"code": "...", "message": "...", "details": [...]}}
Caching ETag / Cache-Control, honouring If-None-Match
Rate limits 429 plus Retry-After and quota headers

Status codes worth getting right: 200/201/204 on success, 400 malformed request, 401 unauthenticated, 403 unauthorised, 404 missing, 409 conflict, 422 semantic validation failure, 429 throttled, 5xx server fault.

Common Authentication Methods

Method Description When to Use
API Key Static token in header Internal services, simple auth
JWT (Bearer) Signed JSON token Web apps, mobile APIs
OAuth 2.0 Authorization framework Third-party integrations
Basic Auth Base64 username:password Legacy, HTTPS-only
mTLS Mutual TLS certificates B2B, zero-trust

Whichever method is used: transport over TLS only, keep credentials in environment variables or a secret manager (never in source control), scope tokens to the minimum required permissions, and design for rotation.

Choosing an Authentication Method

Client type Preferred Why
Server-to-server, same trust domain mTLS or API key No user context; certificates/keys rotate cleanly
First-party web/mobile app OAuth 2.0 + short-lived JWT Login, refresh and revocation handled by the provider
Third-party integration OAuth 2.0 with scopes Granular, user-consented access
Public read-only data API key Simple quota attribution
Legacy system Basic auth over TLS Only if nothing stronger is possible

Idempotency and Retries

POST /api/v1/payments HTTP/1.1
Idempotency-Key: 8f14e45f-ceea-467a-9c1e-1b4a3f2d9c10
Content-Type: application/json
  • Retry only idempotent operations, or POST requests carrying an idempotency key the server records.
  • Retry with exponential backoff and jitter; respect Retry-After on 429.
  • Never retry on 4xx other than 408 / 429 — the request itself is wrong.