Application Programming Interface Design and Communication Questions

Test the candidates ability to design clean application programming interfaces that are intuitive for clients and to clearly explain the design and its trade offs. Coverage includes resource and contract design, request and response formats, error handling and status conventions, versioning and backward compatibility, performance considerations, rate limiting and security basics, and selection of synchronous versus asynchronous communication approaches. At senior levels this expands to event driven patterns, message based systems, gateway patterns, and how interface decisions affect downstream systems and reliability.

EasyTechnical

60 practiced

Explain the difference between path parameters and query parameters in REST API design. Provide examples when each is appropriate (for example, /users/{id} vs /users?country=US&sort=created_at) and discuss how the choice affects caching, SEO, and URL cleanliness.

MediumTechnical

37 practiced

Design a cursor-based pagination scheme for a feed API where new items are frequently inserted. Explain how you would generate stable cursors, ensure monotonic ordering across pages, handle items deleted between requests, and design the response metadata (next cursor, prev cursor, approximate totals).

Sample Answer

Situation: We need a cursor-based pagination for a high-write feed (frequent inserts) that is stable, monotonic, resilient to deletes, and exposes useful metadata.

Approach (high level)- Use an opaque cursor that encodes a deterministic ordering key plus tie-breaker and a version token. Keep cursors small (base64 JSON or signed token).- Order feed by (primary_sort_key DESC, tiebreaker ASC). For feeds typical primary_sort_key = created_at or publish_time; tiebreaker = unique monotonic id (e.g., DB sequence, snowflake).

Generating stable cursors- Cursor payload: {timestamp: 2025-11-22T12:34:56Z, last_id: 987654321, stream_version: 42}- Encode and sign (HMAC) to prevent tampering. The server uses timestamp+last_id as "start after" marker — deterministic even if new items are inserted later.

Ensuring monotonic ordering across pages- Always query with WHERE (created_at < cursor.timestamp) OR (created_at = cursor.timestamp AND id > cursor.last_id) when ordering by created_at DESC, id ASC (or equivalent). This guarantees no item appears twice or skipped when inserts happen with newer timestamps.- Use stable tie-breaker that never reorders (DB primary key or Snowflake).

Handling deletions between requests- If items are deleted between pages: - Continue using cursor marker; missing items are omitted naturally. - Optionally return a delta: items_deleted_count in metadata to help client adjust UI (show “X items removed”). - For stronger consistency, maintain a short-lived tombstone log to surface recently-deleted items IDs if needed.

Response metadata design- next_cursor: encoded marker for next page (last returned item's timestamp+id and current stream_version).- prev_cursor: encoded marker to fetch previous page (first returned item marker and a direction flag). Prev requires careful queries (created_at > marker OR created_at = marker AND id < first_id) and consistent ordering inversion.- approximate_total: inexpensive estimate (e.g., cached count, or count of items in last N minutes extrapolated). Don’t do exact counts for performance; label it “approximate”.- items_deleted_count_since_cursor (optional): small integer.- has_more: boolean for the client to know whether to attempt another page.

Trade-offs and notes- Using created_at as primary key is natural but must be combined with a unique tie-breaker to avoid duplicates when timestamps collide.- If strict snapshot consistency is required across a user session, include a stream_version (e.g., logical clock or max seen timestamp) and serve pages against that stable snapshot (with increased infrastructure cost).- Keep cursors opaque and short; rotate signing keys and support backward compatibility.

This scheme gives deterministic paging even under frequent inserts, minimal server cost, and good UX for feeds.

MediumTechnical

41 practiced

For a high-traffic e-commerce checkout, decide whether order creation and payment capture should be synchronous or asynchronous. Evaluate user experience, latency, coupling to payment providers, transactional guarantees, error propagation to clients, eventual consistency, and rollback or compensation strategies.

Sample Answer

Recommendation: use a hybrid approach—create the order synchronously (fast & durable) and perform payment capture asynchronously with a best-effort optimistic flow and clear UX feedback.

Why:- User experience & latency: creating the order synchronously (write to DB with idempotency key) keeps perceived latency low (<200ms) and gives an immediate order reference. Offload the heavy, variable-latency payment capture to an async worker so the checkout button isn’t blocked by third-party slowness.- Coupling to payment providers: async decouples your API from provider outages/slow responses (use queue + worker + retries) and accepts webhooks for final state.- Transactional guarantees & eventual consistency: model order state machine (PENDING_PAYMENT → PAYMENT_PROCESSING → PAID/FAILED). Use idempotent operations and persistent queues so retries are safe; accept eventual consistency between order and payment status.- Error propagation to clients: surface immediate state (order created, payment pending). Push real-time updates (websocket/notifications/email) or poll endpoint. If payment fails synchronously (quick decline) you can surface it immediately; otherwise show pending and update later.- Rollback/compensation strategies: implement compensation (auto-cancel unpaid orders after a TTL, release inventory, refund on late capture failure). For authorization vs capture flows, consider authorize-on-create and capture-next-step to reduce accidental double-charges.Practical measures:- Use idempotency keys and unique order IDs.- Durable queue (Kafka/Rabbit/SQS) + worker pool with exponential backoff and dead-letter queue.- Use payment provider webhooks to reconcile and mark final states; run periodic reconciliation jobs.- Circuit breakers and throttling to protect system under provider failures.Trade-offs:- Async increases system complexity and requires careful UX to avoid user confusion; but for high-traffic systems it reduces coupling, improves throughput, and provides more robust error handling. Synchronous capture gives immediate finality but ties UX to third-party latency and reduces resilience.

MediumSystem Design

36 practiced

Design a global rate-limiting system that enforces per-API-key limits across many stateless service instances. Describe architectures and algorithms (centralized Redis counter, distributed token buckets, consistent hashing to sticky limiter), trade-offs in latency, accuracy, fault tolerance, and how to handle clock skew and eventual consistency.

Sample Answer

Requirements & constraints:- Enforce per-API-key limits globally (e.g., 100 reqs/min) across many stateless service instances.- Low latency (<10ms extra), high availability, tolerate network partitions, eventual accuracy ok within small error bounds.

High-level options:1) Centralized Redis counter (single writer/atomic INCR + EXPIRE)- Architecture: every instance checks Redis key "api:{key}:{window}" with INCR. Use Redis Cluster for scale and Redis Lua scripts to make operations atomic.- Pros: simple, accurate, easy to reason about.- Cons: added network hop, single-system pressure, higher latency under load, availability tied to Redis.

2) Distributed token bucket (local + sync)- Architecture: each service keeps a local token bucket replenished at rate R/N where N=number of active nodes for that API-key, periodically reconciles with a central coordinator (Redis or Kafka) to borrow/return tokens.- Pros: very low local latency, scalable.- Cons: complex borrowing logic, potential brief over-allowance (bounded).

3) Consistent-hashed sticky limiter (sharded state)- Architecture: assign each API key to a limiter shard using consistent hashing (hash ring + replicas). Requests go via any instance; instance forwards to responsible limiter service (or proxies directly via client-side consistent hashing).- Pros: removes global write contention, deterministic shard routing, can replicate shards for HA.- Cons: extra hop if not co-located, complexity in re-sharding.

Trade-offs:- Latency: local token bucket < sharded limiter ≈ centralized Redis (network dependant).- Accuracy: centralized Redis > sharded limiter > local token bucket (may allow small bursts).- Fault tolerance: replicated/sharded limiters and Redis Cluster with leader election improve availability. Local-only approaches risk split-brain overshoot.

Clock skew & consistency:- Use monotonic clocks for local buckets; avoid wall-clock for rate windows. Prefer leaky/token-bucket algorithms that rely on deltas, not absolute timestamps.- For sliding-window counters, use Redis sorted sets with timestamps or rolling windows to reduce skew impact.- Eventual consistency: allow bounded overages and implement penalty/compensation (throttle/backoff, retroactive billing adjustments).- Use idempotency keys + client-side retry limits to avoid double-counting.

Practical recommendations:- Start with Redis Cluster + Lua script (fast path) for correctness. If latency or scale becomes bottleneck, migrate hot API-keys to sharded limiter services or local token buckets with periodic reconciliation. Monitor overshoot metrics and tune reconciliation frequency, replication factor, and token borrow limits.

HardTechnical

47 practiced

Compare using REST over HTTP/1.1 or HTTP/2 with JSON versus gRPC with protobuf for internal microservice communication. Discuss performance, streaming, schema enforcement, language support, interoperability, observability and how gateway translation to external clients should be managed.

Sample Answer

Short answer: For internal microservice-to-microservice communication, gRPC + protobuf is usually the better choice for performance, streaming, and strong typing; REST+JSON over HTTP/1.1 or HTTP/2 is better for broad interoperability, human-readability, and easier integration with external clients. Choose based on constraints (ecosystem, language mix, ops maturity, need for external gateways).

Detailed comparison:

Performance- gRPC (HTTP/2 + binary protobuf) has smaller payloads, faster (lower CPU/serialization overhead) and benefits from HTTP/2 multiplexing and connection reuse. Good for high QPS and low-latency RPCs.- REST+JSON is heavier (textual), more CPU/ bandwidth; HTTP/2 helps with multiplexing but JSON (de)serialization remains costlier.

Streaming- gRPC natively supports unary, server, client, and bidirectional streaming with flow control via HTTP/2—excellent for long-lived streams and backpressure.- REST can do streaming (chunked, SSE, WebSockets) but patterns are less standardized and require more glue.

Schema enforcement & evolvability- Protobuf schemas are explicit, typed, and support versioning rules (field numbering, optional/required best practices). Strong compile-time guarantees.- JSON is schema-less by default; you can add JSON Schema/Avro but enforcement is external and less integrated into build-time checks.

Language support- gRPC has first-class support across many languages with generated clients/servers, but some languages require extra runtime or have varying maturity.- REST+JSON works everywhere trivially (HTTP client + JSON lib) and is easiest for polyglot environments or scripting.

Interoperability- REST wins for public APIs and heterogeneous clients (browsers, third-party integrators). gRPC requires client stubs or gRPC-web for browsers and can complicate cross-team adoption.- Internally, gRPC’s contract-first approach simplifies consistent APIs.

Observability- Both support metrics/tracing. gRPC provides standardized metadata/ interceptors for propagating tracing IDs and deadlines; HTTP/2 multiplexing can complicate per-request visibility if not instrumented.- REST leverages existing HTTP-based observability tools (access logs, existing proxy metrics). Use distributed tracing (W3C Trace Context) in either case.

Gateway translation for external clients- Use an API gateway/adapter layer: expose REST/JSON to external clients while translating to internal gRPC. Options: envoy with gRPC-JSON transcoder, custom gateway service, or grpc-gateway. Implement authentication, rate-limiting, and field-level transforms at the gateway.- Keep internal contracts stable; do transformation and versioning at the gateway rather than exposing internal protobufs directly.

Practical trade-offs & recommendations- If internal services require low latency, high throughput, streaming, and strong schemas → adopt gRPC+protobuf.- If many external or ad-hoc clients (browsers, third parties) or simpler operational model desired → REST+JSON.- Hybrid: internal gRPC, gateway for REST/JSON externally. Invest in CI-generated stubs, automated schema validation, consistent tracing propagation, and robust gateway tests.

Unlock Full Question Bank

Get access to hundreds of Application Programming Interface Design and Communication interview questions and detailed answers.

Join thousands of developers preparing for their dream job.