notes

API Notes

Detailed notes on REST APIs with additional comparison info and examples.

REST (Representational State Transfer) is an architectural style for distributed hypermedia systems. It uses standard HTTP methods and stateless communication.

  • HTTP methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
  • Resources are identified by URLs (endpoints)
  • Use JSON (or XML) for request/response payloads
  • Statelessness: each request contains all context

  1. Use plural nouns for resource names (e.g., /users, /orders).
  2. Use HTTP status codes correctly (200, 201, 400, 401, 403, 404, 409, 500, etc.).
  3. Support filtering, sorting, paging via query params (e.g., ?page=1&per_page=25&sort=-createdAt).
  4. Version APIs using path or headers (e.g., /v1/users).
  5. Keep APIs stateless and document with Swagger/OpenAPI.

  • Use HTTPS only.
  • Authenticate via OAuth 2.0, JWT, API keys, or Basic Auth over TLS.
  • Authorize using RBAC/ABAC rules and least privilege.
  • Validate and sanitize all input; avoid injection attacks.
  • Rate-limit abusive clients and log requests for auditing.

GET /api/v1/products              # list products
GET /api/v1/products/{id}         # get product
POST /api/v1/products             # create product
PUT /api/v1/products/{id}         # update product
PATCH /api/v1/products/{id}       # partial update
DELETE /api/v1/products/{id}      # delete product

Use consistent request/response schemas with a top-level object (e.g., {"data": ...}, {"error": ...}).

REST is resource-centric and flexible, SOAP is protocol-heavy with strict XML envelope, GraphQL is query-centric and allows clients to select fields.

  • REST: easy caching, ideal for standard CRUD, widely supported.
  • SOAP: strong contracts (WSDL), built-in security (WS-Security), more complex.
  • GraphQL: single endpoint, avoids over-fetching, but requires careful query complexity management.