APIs

APIs

HTTP semantics, retries, idempotency, GraphQL tradeoffs, and contract design.

• API Design

  6 studies
  1. 1.API Design — Naming, Paths, Routing & ContractsInterviewers rarely ask you to design REST. They ask whether /getUser is wrong, how deep nesting should go, when to version, which status codes clients can trust, and how you paginate without breaking caches. This hub maps naming, nesting, methods/status, versioning, and list contracts.
  2. 2.Resource Naming & URI Design — Plurals, Case, IDs & CollectionsAlmost every API design interview starts with a path sketch. Interviewers check plural nouns, verbs smuggled into URLs, kebab vs snake consistency, opaque IDs, and whether filters live in the query string. We design the nouns idempotent retries operate on — without re-teaching Idempotency-Key.
  3. 3.Path Nesting, Routing & Actions — Depth Limits & Sub-resourcesNesting feels natural until clients need cross-org search, gateways rewrite paths, or authz must check every segment. Cap depth around 2–3 resource pairs, keep a canonical item URL, and model non-CRUD verbs as :customAction or /actions — not controller soup.
  4. 4.HTTP Methods & Status Codes for Resource APIsInterviewers expect CRUD mapped to methods and status codes clients can automate on. Always-200 with {success:false} is a classic fail. This lesson covers GET/POST/PUT/PATCH/DELETE, 201 Location, Prefer, If-Match, and the 4xx grid — pointing POST retries and 429 at the Idempotency and rate-limit docs.
  5. 5.API Versioning Strategies — URL, Header & Query TradeoffsShould we put /v1 in the path is a classic interview trap. Prefer additive, non-breaking evolution; version only when you must break contracts; then compare URL vs media-type/header vs query (api-version=) with Sunset and a migration window.
  6. 6.Pagination, Filtering, Sorting & Partial ResponsesList endpoints make or break API UX. Interviewers ask offset vs cursor, why page 50 drifts under inserts, how to sort stably, where filters live, and whether fields= helps mobile. Prefer cursors for large append-heavy feeds; always define a total order.

• GraphQL

  6 studies
  1. 1.GraphQL — Schema Design, N+1, Federation & When Not to Use ItGraphQL is a query language plus a typed schema so clients can ask for the fields they need on one endpoint. This hub is the decision map for schema nullability, resolver N+1, federation, and when REST or gRPC is the better tool.
  2. 2.Schema Design — Types, Nullability, Inputs & EvolutionA GraphQL schema is a versioned product contract. Nullability, input types, and additive evolution decide whether the next ship breaks clients or only adds a field they can ignore.
  3. 3.Resolvers & N+1 — DataLoader, Batching & Query PlanningGraphQL walks the selection set and calls a resolver per field. A child fetch per parent row is the N+1 outage. DataLoader batches those keys inside a single request, and a join or a persisted plan beats the loader when the shape is fixed.
  4. 4.Queries, Mutations & Subscriptions vs REST/gRPCGraphQL operations are Query for a read, Mutation for a write, and Subscription for a product event stream. Map them to REST methods and gRPC shapes, then leave CDN reads, idempotent POST retries, and mesh streams in their own clusters.
  5. 5.AuthZ, Complexity Limits & Abuse ProtectionA GraphQL endpoint lets the client choose depth, breadth, and aliases. Authentication at the door is not enough. Authorize each sensitive field, score the query, and prefer persisted documents for first-party apps.
  6. 6.Federation, Gateways & Schema Stitching TradeoffsFederation, schema stitching, and a monolith schema are ownership models. A gateway is worth it when domain teams and a platform SLO both exist. It does not remove N+1, field AuthZ, or the need for a cost budget inside each subgraph.

• gRPC & Protobuf

  6 studies
  1. 1.gRPC & Protobuf — Contracts, Streaming & API EvolutiongRPC is HTTP/2 + Protocol Buffers + generated stubs: a contract-first RPC stack for service-to-service calls. Interviewers care less about binary speed and more about contracts, streaming shapes, evolution rules, and when gRPC is the wrong tool (browsers without grpc-web, public REST ecosystems). This hub maps the cluster: schemas, unary vs streaming, deadlines/errors, load balancing/channels, and the REST/GraphQL decision matrix.
  2. 2.Protobuf Schemas — Fields, Wire Types & CompatibilityProtobuf's wire identity is the field number, not the field name. Types, optional / repeated / map, proto3 defaults, reserved, and wire types determine whether two binaries can talk forever. Interviewers probe: can you add a field safely? Why never reuse numbers? What goes wrong with JSON mapping?
  3. 3.Unary vs Streaming RPCs — Client, Server, Bidi & BackpressuregRPC RPCs are not only request/response. Four shapes — unary, server-streaming, client-streaming, bidirectional — change memory, latency, and failure modes. Senior interviews ask when each fits, how HTTP/2 flow control provides backpressure, and which anti-patterns (unbounded server streams, ignoring cancel) blow up production.
  4. 4.gRPC Deadlines, Cancellation & Error ModelgRPC calls carry a deadline (absolute time), not only a per-hop timeout. Cancellation propagates so servers stop work the client no longer needs. Errors are status codes + optional details + trailers, not HTTP status alone. Interviewers compare this to HTTP codes and ask which statuses are retryable.
  5. 5.gRPC Load Balancing, Name Resolution & Channel HealthgRPC clients open a channel to a resolved set of addresses and may balance RPCs client-side (pick_first, round_robin, …) or through a proxy (Envoy/L7). Name resolution (DNS, xDS), keepalive, health checks, and sticky affinity for bidi decide whether streams survive deploys. Cross-link the general Load Balancing cluster — here we focus on gRPC-specific channel behavior.
  6. 6.gRPC vs REST/JSON & GraphQL — When to Choose WhatThere is no universal winner. Choose gRPC for internal typed service meshes and streaming; REST/JSON for public, cacheable, browser-native HTTP; GraphQL when many clients need flexible graphs of data from a BFF. Honest senior answers include when REST wins — not only when binary RPC looks faster on a whiteboard.

• Idempotency

  6 studies
  1. 1.API Idempotency KeysStripe-style Idempotency-Key for safe retries — fingerprint, unique (account,key), in_progress/completed, response cache, ~24h TTL.
  2. 2.At-Least-Once vs Exactly-Once DeliveryAt-most-once loses; at-least-once duplicates; exactly-once needs transactional producer+consumer+sink; effectively-once is idempotent consumers + dedup.
  3. 3.Request Fingerprinting for Idempotent APIsCanonical JSON (sorted keys, stable numbers) hashed with method+path; include/exclude map; Stripe-style 422 on mismatch; schema-evolution with null defaults.
  4. 4.Retry Storms, Backoff & JitterNaive retries amplify outages. Combine exponential backoff, full jitter, Retry-After, circuit breakers, client budgets, and idempotency keys.
  5. 5.Idempotent HTTP Methods & Safe RetriesRFC 9110 — safe vs idempotent. GET/HEAD/OPTIONS/TRACE safe; PUT/DELETE idempotent but not safe; POST not idempotent; PATCH depends. Idempotency-Key still needed for POST and for concurrent PUT races.
  6. 6.Transactional Outbox & Inbox PatternsDual-write is the bug. Write domain row + outbox row in one DB transaction; poller/CDC publishes; inbox dedupes at-least-once deliveries into effectively-once processing.