API Design and Integration Questions

Design and evaluate application programming interfaces for external and internal consumption. Topics include resource and schema modeling for RESTful APIs, GraphQL schema and resolver design for diverse clients, and when to choose gRPC style remote procedure calls for high performance internal services. Candidates should address consistent error responses including problem details, pagination and filtering strategies, versioning and deprecation plans, idempotency keys and safe retry semantics, rate limiting headers and status codes, authentication and authorization patterns, contract testing, monitoring and observability, and how to balance backward compatibility with iteration velocity.

HardSystem Design

24 practiced

Design an integration platform (iPaaS-like) to connect third-party systems with your APIs. Include connector architecture, schema mapping and transformation engine, reliable delivery semantics (at-least-once vs exactly-once), developer tooling for mapping fields, sandboxing, multi-tenant isolation, and monitoring for connector health and message failures.

Sample Answer

**Overview & goals**Design an iPaaS to let third parties connect to our APIs with low friction, secure multi-tenant isolation, reliable delivery, and good DX. Key product goals: fast onboarding, predictable SLAs, developer self-service, and operational visibility.

**High-level architecture**- Connector runtime (stateless workers + secrets store) behind API Gateway- Control plane (tenant config, connector catalog, mapping repository, audit)- Message bus (durable queue / Kafka) for decoupling and replay- Transformation engine service (scalable, sandboxed)- Delivery workers with retry/offset tracking- Monitoring + alerting + dashboard

**Connector architecture**- Packaged connector model: metadata + auth adapter + schema adapter + runtime plugin- Connectors run in per-tenant sandbox (K8s namespaces or serverless containers) with resource limits- Pluggable auth (OAuth2, API key, TLS, SFTP) and rate-limiters

**Schema mapping & transformation engine**- Canonical intermediate schema (JSON-LD or protobuf) to normalize source/target- Visual mapping UI for drag-drop field mapping, expressions, and reusable mapping templates- Transformation engine supports function library, JavaScript hooks, and WASM for heavy custom logic- Versioned mappings for safe deploy & quick rollback

**Reliable delivery semantics**- Default: at-least-once with idempotency helpers (idempotency keys, dedupe store)- Exactly-once offered for premium connectors using transactional outbox + consumer-side idempotency + at-least-once + dedupe TTL or exactly-once stream semantics (Kafka transactions)- Expose contract: once-per-message SLA, retry policy, dead-letter queue

**Developer tooling & sandboxing**- Self-service portal: connector builder, mapping IDE, SDKs, CLI- Test sandbox with synthetic data, replay, and "dry-run" simulation showing transformed payloads and diffs- Staging tenants for integration tests before production

**Multi-tenant isolation**- Logical isolation via tenant IDs, per-tenant encryption keys, RBAC- Strong isolation for runtimes (separate namespaces / ephemeral containers)- Rate-limits and quota management per tenant

**Monitoring & observability**- End-to-end traces (distributed tracing), per-connector metrics (latency, success rate), DLQ size, retry counts- Health dashboards, SLA/RTO alerts, automatic circuit breaker for failing connectors- Audit logs and usage billing metrics

**Trade-offs & roadmap**- Start with at-least-once + strong idempotency primitives to expedite launch; add exactly-once for high-value integrations- Prioritize UX for mapping UI and sandboxing to reduce support costs- Roadmap: connector marketplace, ML-assisted mapping suggestions, policy-as-code for data compliance

This design balances developer experience, operational reliability, and tenant security while allowing incremental delivery of stronger guarantees.

HardSystem Design

28 practiced

Architect a hybrid API platform that supports REST, GraphQL, and gRPC, with features including an API gateway, schema/contract registry, developer portal with SDK generation, centralized monitoring, and per-tenant quotas. Define high-level components, control plane vs data plane responsibilities, and how you would enforce cross-cutting policies (auth, rate limits, versioning) at scale (millions of requests per day).

Sample Answer

**High-level summary (PM perspective)** I’d deliver a hybrid API platform enabling REST, GraphQL, and gRPC with strong governance, developer experience, and multi-tenant controls — prioritized by time-to-market for SDKs, security, and observability.

**Core components**- API Gateway (data plane): protocol translation (REST⇄gRPC, GraphQL proxy), TLS, request routing, edge auth hooks, per-tenant quotas, rate-limit token buckets.- Control Plane: config store, policy engine, schema/contract registry (OpenAPI, GraphQL SDL, protobuf), versioning metadata, tenant configs.- Developer Portal: self-service onboarding, interactive docs, SDK generation (OpenAPI/Swagger-codegen, GraphQL Codegen, protoc), key management.- Monitoring/Observability: centralized metrics (Prometheus), traces (OpenTelemetry + Jaeger), log aggregation, tenant-level dashboards, alerting.- CI/CD & Broker: schema validation, contract tests, canary rollout manager.

**Control plane vs Data plane**- Control plane: authoring, policy definitions, quota rules, schema registry, tenant RBAC, policy distribution (push + incremental sync).- Data plane: runtime enforcement—fast path for auth, rate-limits, routing; consult cached policies; fall back to control plane only on miss.

**Cross-cutting policies at scale**- Auth: JWT/OAuth at gateway with introspection caching + mTLS for service-to-service; offload heavy checks to identity provider, cache tokens per tenant.- Rate limits/quotas: distributed token bucket implemented in gateway with Redis/consistent-hash local cache + periodic reconciliation to control plane; enforce per-tenant and per-key tiers.- Versioning: registry enforces semantic versioning; gateway supports routing by header/path for blue/green and header-based canaries; GraphQL handled via field deprecation + schema stitching for backward compatibility.

**Scalability & reliability**- Autoscale data plane horizontally; use sidecar proxies for service mesh workloads; shard registry by tenant groups; use CDNs and edge points for global latency.- SLOs: 99.95% gateway availability, 100ms P50 request latency target (configurable by API class).- Observability: per-tenant billing/usage pipelines, anomaly detection, SLA dashboards.

**Product trade-offs / roadmap**- Phase 1: REST + gateway + registry + portal + SDK gen for top languages. - Phase 2: Add GraphQL and gRPC translation, advanced policy engine, enterprise features (mTLS, quotas, SSO). - KPIs: developer onboarding time, API adoption, error rates, quota violations, SLA compliance.

HardSystem Design

22 practiced

Design a consumer-driven contract testing CI pipeline for an organization of multiple teams. Include steps: contract creation by consumers, publishing to a broker, provider verification, automated gating in provider CI, and rollback policies if verification fails in production. Describe tooling choices and security considerations for a shared contract registry.

Sample Answer

**Clarify goals & constraints**- Consumer-driven contracts (CDCs) to prevent API regressions, enable independent team deploys, and enforce backward compatibility.- Multi-team org with shared broker, decentralized ownership, and strict security/compliance.

**High-level pipeline**1. Consumer creates/updates contract (Pact or OpenAPI contract tests) in their feature branch.2. CI: run consumer unit + contract tests → publish contract artifact to Pact Broker (or Spectral + AsyncAPI registry) with semantic versioning and metadata (team, environment).3. Provider CI: on contract publish or PR, provider triggers verification job that fetches relevant contracts from broker, runs provider verification suite (integration tests + provider states).4. Automated gating: provider CI blocks merges for contracts that fail verification. Successful verifications tag contract as “verified” and promote to staging/production channels.5. Deployment: only providers with verified contracts promoted automatically; otherwise fail gating and prevent release.

**Rollback & production failures**- Canary deployments + feature flags for consumers; monitor contract-metric alerts.- If runtime incompatibility occurs, rollback strategy: - Immediate: feature-flag off for consumers, revert provider release via CI rollback, or serve compatibility shim. - Postmortem: create blocking contract update, require provider compatibility fix, run regression verification before re-release.

**Tooling choices**- Contract: Pact (wide ecosystem) or OpenAPI + Dredd for REST; Pact Broker for registry.- CI: GitHub Actions/GitLab CI/Jenkins orchestrating verification jobs.- Deployment: ArgoCD/Spinnaker for gated deploys + LaunchDarkly for flags.- Observability: Prometheus + Grafana, SLOs for contract violations.

**Security & governance for shared registry**- RBAC on Pact Broker (team-scoped workspaces), OAuth/OIDC SSO integration, TLS, signed artifacts, audit logs.- Network: broker in private VPC with VPN/zero-trust access; read-only tokens for provider CI; rotate credentials.- Governance: contract lifecycle policy, naming conventions, SLA for verification turnaround, automated expiry of stale contracts.

**Measure success**- Reduced runtime contract failures, faster independent deploys, mean time to verify, and fewer rollbacks.

HardSystem Design

22 practiced

Describe a safe rollout and rollback plan for a breaking API change. Include canary deployment strategies, compatibility tests, gateway transformations to provide backward compatibility, feature flags, monitoring signals that trigger automatic rollback, and a communications plan to notify partners and internal teams.

Sample Answer

**Situation & goals (brief)** As a Technical Product Manager, my goal is to deploy a breaking API change with minimal customer impact, fast rollback if needed, and clear partner/internally-facing communication.

**Plan overview**- Use semantic versioning (v2) + compatibility gateway transforms so v1 clients continue working.- Canary rollout behind a feature flag + progressive traffic shift (1% → 5% → 25% → 100%) with automated gates.- Strong safety net: contract & compatibility tests, runtime canary checks, and monitored SLA/telemetry-driven rollback.

**Pre-deployment**- Define success criteria: latency delta < 20%, error rate < 0.1%, no contract violations, 95th percentile response time within SLO.- Create backward-compatible gateway transformations: map v1 request/response shapes to v2 internally; inject deprecation headers for v1 clients.- Implement feature flag controlling v2 behavior and header-based/consumer-scoped targeting for partner pilots.- Automated contract tests (consumer-driven contracts), integration tests in CI, and staging full replay of production traffic (or subset).

**Canary strategy**- Start with internal users and CI traffic, then external partner pilot via allowlist.- Traffic schedule: 1% (30m) → 5% (1h) → 25% (2h) → 100% (gradual). Each step gated by automated checks.- Observe both technical and business metrics per consumer.

**Monitoring & automatic rollback signals**- Real-time metrics: - Error rate (5xx) increase > 0.5 percentage points or relative increase > 200% - Latency P95 increase > 50% or absolute > SLO breach - Contract validation failures > 0 - Key business metrics drop > 5% (e.g., successful transactions) - Increased retries from SDKs or gateway- Alerts tied to runbook: automated rollback if any gate breached for N minutes; otherwise page on warning.- Rollback implemented by toggling feature flag to route back to v1 or disabling v2 deployment via orchestrator.

**Communications**- Pre-release: notify partners + internal teams (support, sales, docs) with changelog, migration guide, test endpoints, and pilot invite; publish deprecation schedule.- During rollout: automated status updates to status page and Slack channel; targeted partner pings for canary participants.- Post-rollback/post-success: post-mortem within 48 hours, migration checklist, updated docs, and timeline for v1 deprecation.

**Trades & rationale**- Gateway transforms buy time for partners but add runtime complexity—use them short-term while partners migrate.- Feature flags and consumer-scoped rollouts minimize blast radius.- Automated gates enable quick safe decisions; human-in-the-loop for borderline cases.

This approach balances product velocity with developer experience and operational safety, ensuring partners have time and clear signals to migrate while protecting customers and business metrics.

MediumTechnical

27 practiced

Provide a JSON example of a Problem Details (RFC 7807) response you would return for a failed POST /orders call, including: type, title, status, detail, instance, a machine-readable error_code, correlation_id, and suggested remediation. Explain each field's purpose briefly.

Sample Answer

**Sample JSON (Problem Details - RFC 7807)**

json

{
  "type": "https://api.example.com/problems/invalid-order",
  "title": "Invalid order payload",
  "status": 400,
  "detail": "Order contains invalid 'items' array: item[0].quantity must be >= 1.",
  "instance": "/orders/attempts/7f3a9b2c",
  "error_code": "ORDER_INVALID_ITEMS_QUANTITY",
  "correlation_id": "8a7f6e5d-1234-4bcd-9f00-1a2b3c4d5e6f",
  "remediation": "Ensure each item has a numeric 'quantity' >= 1. See API docs: /docs/#create-order and retry the request."
}

**Field purposes (brief, product-manager view)**- type: URI identifying the problem type so clients and docs can map behavior and automated handling.- title: Human-readable short summary for UIs and logs.- status: HTTP status code to align transport-level semantics (400 = client error).- detail: Specific human-friendly explanation of what failed (helps support and debugging).- instance: Resource/attempt identifier for tracing this specific failed request in logs.- error_code: Machine-readable code engineers and clients use for conditional logic and metrics.- correlation_id: Trace ID to tie this request across services, essential for debugging and SRE.- remediation: Actionable next steps for developers or users to fix and retry (improves developer experience).

Unlock Full Question Bank

Get access to hundreds of API Design and Integration interview questions and detailed answers.

Join thousands of developers preparing for their dream job.