API Design & Communication Protocols

#Introduction

An API is a contract between a system and its clients, and once published it's hard to change. Good API design makes systems easy to use, safe to retry and possible to evolve.

#REST Resource Design

Model resources (nouns) and use HTTP methods as verbs:

Guidelines: plural nouns, lowercase with hyphens (/order-items), no verbs in paths (/getOrders ❌), and consistent naming across the whole API.

#Methods: Safe and Idempotent

Idempotency matters because networks fail: a client that times out doesn't know whether its request succeeded, and will retry.

Idempotency Keys

Make POST safe to retry by having the client send a unique key:

POST /payments
Idempotency-Key: 3f9a1c7e-58b2-4f2a-9d1e-1b2c3d4e5f6a
Content-Type: application/json

{ "orderId": "ORD-1001", "amount": 2499.00 }

Payment APIs such as Stripe and Razorpay work this way.

#Status Codes

#Consistent Error Responses

Use one error format everywhere — the Problem Details standard (RFC 9457), supported by Spring 6 (ProblemDetail):

{
  "type": "https://api.example.com/errors/insufficient-stock",
  "title": "Insufficient stock",
  "status": 409,
  "detail": "Only 2 units of SKU-1 are available.",
  "instance": "/orders",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

#Pagination

Never return unbounded lists.

For large or frequently changing datasets (feeds, logs), cursor pagination is the scalable choice — it maps to keyset queries like WHERE id < ? ORDER BY id DESC LIMIT 20 (see the SQL chapters).

{
  "items": [ … ],
  "nextCursor": "eyJpZCI6ODB9",
  "hasMore": true
}

#Filtering, Sorting and Field Selection

GET /orders?status=PAID&createdAfter=2026-10-01&sort=-createdAt&fields=id,total,status

Validate and whitelist parameters, index the columns you allow filtering on, and cap page sizes.

#Versioning

Prefer additive, backward-compatible changes (new optional fields) so new versions are rarely needed; when they are, run both for a deprecation period and announce removal dates (Deprecation / Sunset headers).

#Other API Concerns

• Authentication with OAuth2 bearer tokens; HTTPS only.
• Rate limiting with 429 responses.
• Caching of GET responses with Cache-Control and ETag (conditional requests return 304 Not Modified).
• Optimistic concurrency with ETag / If-Match to prevent lost updates (412 Precondition Failed).
• Documentation with OpenAPI (springdoc-openapi generates it from Spring controllers).

#REST vs GraphQL vs gRPC

#Real-Time Communication

Webhooks Done Right

• Sign payloads (HMAC) so receivers can verify them.
• Retry with back-off; receivers must be idempotent (deduplicate by event ID).
• Respond quickly (2xx) and process asynchronously.

#Key Takeaways

• Design around resources and standard HTTP methods; be consistent.
• Know safe and idempotent methods; use idempotency keys for retried POSTs.
• Return precise status codes and one consistent error format (Problem Details).
• Paginate everything — cursors for large, changing datasets.
• Evolve additively; version only for breaking changes.
• REST for public APIs, gRPC internally, GraphQL for flexible clients; SSE/WebSockets/webhooks for real-time.