Application Programming Interface Design and Strategy Questions

Covers the design, developer experience, and strategic operating decisions for Application Programming Interfaces and developer platforms. Candidates should demonstrate core design principles such as simplicity, consistency, discoverability, clear naming and conventions, intuitive resource modeling, robust error handling, stability, backward compatibility, and explicit versioning strategies. They should understand trade offs among interface paradigms including Representational State Transfer style APIs, Graph Query Language approaches, and remote procedure call frameworks such as gRPC, and how those choices affect discoverability, latency, schema evolution, client ergonomics, testing, and mocking. The topic also includes the developer facing surface area beyond the interface itself: documentation, quickstart guides, sample code, software development kits, command line tools, interactive explorers, sandbox environments, and other onboarding artifacts that reduce friction. Candidates should be able to identify common friction points such as unclear documentation, complex setup and authentication flows, unhelpful error messages, inconsistent or surprising behaviors, slow feedback loops, and endpoints that are hard to mock or test, and propose concrete engineering and process solutions. Measurement and optimization expectations include onboarding and adoption metrics such as time to first successful call, time to first meaningful result, onboarding success rates, developer satisfaction and sentiment, adoption and churn, support and integration costs, error rates and latency, and how to instrument and monitor the developer journey. Engineering practices to discuss include stable contract design, semantic versioning and compatibility guarantees, schema and contract testing, clear deprecation policies, monitoring and observability for developer journeys, automated client generation and migration tooling, authentication and rate limiting strategies, webhook and event mechanisms, and monetization or partnership models for platform growth. Senior candidates should connect technical and experience decisions to product and business outcomes, explaining how design choices drive adoption, reduce support load, enable ecosystem growth, and preserve long term platform velocity, and should provide concrete examples of improvements implemented or proposed and how their impact was measured.

MediumSystem Design

47 practiced

Design a REST API for a simple secure file-sharing service used by third-party developers. The API must support: uploading large files in chunks, sharing links with permissions (read-only, edit), listing files with pagination, and webhook notifications on file upload. Describe endpoints, request/response shapes at a high level, authentication approach, idempotency, and considerations for large-file handling and quotas.

Sample Answer

**Overview & goals**Design a developer-facing REST API for secure file sharing that supports chunked large uploads, shareable links with permissions, pageable listings, webhooks for uploads, idempotency and quota controls. Focus: simplicity, predictable errors, security, good developer experience.

**Endpoints (high-level)**

- POST /v1/uploads - Starts upload session: body { "filename", "size", "content_type" } - Response { "upload_id", "chunk_size", "upload_url" }- PUT /v1/uploads/{upload_id}/chunks - Upload chunk(s) with headers: Content-Range, Idempotency-Key - Response { "received_bytes", "status":"incomplete" }- POST /v1/uploads/{upload_id}/commit - Finalize: body { "checksum" } → returns file_id, metadata - Response { "file_id", "url", "size", "checksum" }

- GET /v1/files - List files with pagination: query ?page_size=50&cursor=abc - Response { "files":[{id,name,created_at,size,owner}], "next_cursor" }

- GET /v1/files/{file_id} - Get metadata and sharing info

- POST /v1/files/{file_id}/share - Create share link: body { "expires_at", "permissions": "read"|"edit", "max_downloads" } - Response { "share_id", "link", "permissions", "expires_at" }

- DELETE /v1/shares/{share_id} - Revoke a link

- POST /v1/webhooks - Register webhook: { "url", "events":[ "file.uploaded" ], "secret" }

**Request/Response shape examples**Request to start upload:{ "filename":"big.mov", "size":1234567890, "content_type":"video/mp4"}Commit response:{ "file_id":"f_123", "url":"https://cdn.example.com/f_123", "size":1234567890, "checksum":"sha256:..."}

**Authentication & authorization**- OAuth 2.0: Client Credentials for server-to-server; Authorization Code for end-user flows.- Each request carries Bearer token. Scopes: files:read, files:write, shares:manage, webhooks:manage.- Enforce RBAC for team accounts and owner vs collaborator checks on share creation.

**Idempotency**- Require Idempotency-Key header for start-upload and chunk upload and commit endpoints.- Server tracks keys per client and upload operation; safe retry returns original resource or consistent error.

**Large-file handling**- Use upload sessions + chunked PUTs with Content-Range.- Provide pre-signed upload_url (temporary) pointing to object store (S3) for direct client upload (reduces server bandwidth). Server validates chunk checksums on commit.- Support parallel chunk uploads; maintain bitmap of received chunks.- Resume by querying /v1/uploads/{upload_id}/status.

**Quotas & rate limits**- Per-tenant quotas: total storage, per-file size limit, daily bandwidth and concurrent uploads.- Return clear 429 or 413 with quota details and retry-after.- Admin APIs to view and increase quotas; webhooks for quota-exhaustion events.

**Webhooks**- Deliver events (file.uploaded) with retry/backoff; sign payloads with HMAC secret.- Idempotent webhook payloads include event_id and timestamp so consumers can dedupe.

**Security & compliance**- Encrypt at rest, TLS in transit, signed pre-signed URLs with short TTLs.- Audit logs for share creation and downloads; configurable retention for compliance.

**Developer experience**- SDKs and sample code for chunked uploads, clear error codes (4xx/5xx), sandbox with lower quotas, detailed docs and upload diagnostics.

HardTechnical

93 practiced

Design a security posture for an API platform to detect and mitigate abuse and credential compromise. Your design should cover detection (anomaly detection, rate anomalies), automated mitigation (throttling, token revocation), credential lifecycle (rotation, short-lived tokens), incident response playbooks, and partner communication. Explain trade-offs between blocking false positives and protecting customers.

Sample Answer

**Situation & goals**Design a product-grade security posture for an API platform that detects abuse and credential compromise while preserving developer experience and business continuity.

**Detection**- Telemetry: capture request metadata (API key, token ID, IP, geo, device, user-agent, request path, payload hash, timestamps).- Behavioral models: baseline per-entity (client app, API key, account) for volume, rate, error-rate, latency, and endpoint access patterns using statistical (EWMA, z-score) + ML anomaly detectors.- Rule-based detection: spike in 4xx/5xx, sudden increase in token refreshes, credential stuffing signature (many failed auths from same IP across users).- Rate anomaly engine: compare short/long windows (1m vs 24h) and score anomalies.

**Automated mitigation**- Gradual throttles: soft rate limiting (429) escalating to hard limits per risk score.- Risk-based token actions: mark token as suspect (reduced scope), force short-lived refresh, or immediate revocation for high-confidence compromise.- Quarantine mode: isolate client to read-only or sandbox endpoints while investigating.

**Credential lifecycle**- Short-lived access tokens (minutes) + rotating refresh tokens with detected reuse invalidation.- Enforce MFA and delegated rotation APIs for partners; provide SDKs and docs to simplify rotation.- Automated rotation reminders and one-click rotate in dashboard for compromised keys.

**Incident response & playbooks**- Triage playbook: Detect → Score → Contain (throttle/revoke) → Notify → Forensics → Remediate → Restore.- Forensics: raw logs, replay capability, affected-scope matrix.- Post-incident: root-cause, compensating controls, SLA impact and compensation policy.

**Partner communication**- Tiered notifications: real-time in-console + email for high severity, weekly digest for low.- Templates: action required, remediation steps, temporary mitigations, rotation links.- Partner portal: incident timeline, affected tokens, API calls sample, support escalation.

**Trade-offs**- Aggressive blocking reduces attacker success but increases false positives and developer friction; prefer phased mitigations (soft throttles, reduced scopes) before hard blocks.- Invest in high-fidelity detection (contextual signals) to minimize false positives; when in doubt, favor temporary risk-limited actions and clear partner communication to preserve trust.

As TPM I’d define OKRs (detection accuracy, mean time to remediate), prioritize instrumentation, and deliver APIs/UX that make secure practices frictionless for partners.

MediumTechnical

46 practiced

Design authentication/authorization flows for a public API platform that must support: first-party clients (mobile/web), third-party apps (on behalf of users), and machine-to-machine integrations. Discuss when to use OAuth2 (including PKCE), API keys, JWTs, and mutual TLS; include token lifetimes, refresh, and best practices for rotating credentials.

Sample Answer

**Approach / high-level recommendation**

Design three canonical flows: first‑party user clients (mobile/web), third‑party apps acting for users, and machine‑to‑machine (M2M). Choose protocols by threat model, usability, and revocation needs.

**First‑party mobile & web (users)**- Use OAuth2 Authorization Code with PKCE (prevents auth code interception). Issue short‑lived access tokens (e.g., 5–15 min) as JWTs for stateless validation and a refresh token (rotating, single‑use) valid ~14–30 days.- Refresh tokens: rotate on use and revoke previous; persist session on server for revocation/blacklist.- Example: mobile app starts PKCE flow, receives JWT access token + rotating refresh token.

**Third‑party apps (on behalf of users)**- Use OAuth2 Authorization Code (PKCE optional for public clients) with explicit scopes and consent. Use refresh tokens but require tighter scopes and shorter lifetimes (access 5–15 min, refresh 7–30 days).- Support token revocation via an introspection/revocation endpoint and granular scope claims in JWT.

**Machine‑to‑machine integrations**- Use OAuth2 Client Credentials or mTLS for high assurance. For low risk, client credentials with client_secret rotated frequently; for sensitive APIs require mTLS to bind client cert to identity.- Access tokens: JWTs with short lifetime (5–60 min). No refresh tokens — client re‑requests token.

**API keys**- Use for simple server-to-server or non‑user‑context low‑privilege access (rate limiting, analytics). Treat as long‑lived credentials but store hashed in DB, allow easy rotation, restrict by IP, quota, and scope. Avoid in-browser or mobile apps.

**JWTs**- Use signed (RS256) JWTs with minimal claims: sub, aud, exp, iat, jti, scope. Keep lifetime short and validate audience/issuer. Keep token size small.

**Mutual TLS**- Use for highest assurance M2M (financial, healthcare). Bind TLS cert to client identity, rotate certs via automated CA, and require pinning/rotation policies.

**Token lifetimes & refresh**- Access token: 5–15 min (user), 5–60 min (M2M).- Refresh token: shortish (7–30 days), single‑use rotation, revoke on suspicious activity.- Revoke via revocation endpoint and publish introspection.

**Credential rotation & best practices**- Automate rotation (secrets manager), rotate client_secrets and API keys regularly (90 days), support zero‑downtime rotation (dual keys).- Store secrets server‑side only; never in client code. Hash API keys at rest.- Monitor usage, anomaly detection, enforce rate limits, and provide developer UX: dashboard, key expiry warnings, one-click rotate.- Provide clear docs with examples, scopes, and recommended flows per client type.

This design balances security, developer experience, and operational manageability for a public API platform.

EasyTechnical

56 practiced

Define API discoverability in the context of large internal and external developer ecosystems. Describe three concrete initiatives or features you would ship to make APIs more discoverable by engineers in other teams or partner companies.

EasyTechnical

43 practiced

List common HTTP status codes a developer-facing API should use and explain the typical semantic for each: 2xx (200, 201, 202, 204), 4xx (400, 401, 403, 404, 409, 422, 429) and 5xx (500, 502, 503). For each code mention when you'd use it and one common mistake engineers make when using it.

Sample Answer

**Overview (role perspective)** As a Technical PM I expect clear, predictable semantics so SDKs, docs and error handling are consistent for developer experience and monitoring.

**2xx — Success**- 200 OK — Use: GET or POST returning resource/body. Mistake: using 200 for partial success or ignoring status for errors in body.- 201 Created — Use: resource created; include Location header. Mistake: returning 200 instead of 201 or omitting Location/id.- 202 Accepted — Use: async work accepted (enqueue). Mistake: clients assume completion; no status link provided.- 204 No Content — Use: successful action with no body (DELETE, vacuum PUT). Mistake: returning body with 204 or using it for failures.

**4xx — Client errors**- 400 Bad Request — Use: malformed JSON/validation failed. Mistake: vague messages; no field-level errors.- 401 Unauthorized — Use: missing/invalid auth. Mistake: using 403 when token expired; omit WWW-Authenticate header.- 403 Forbidden — Use: authenticated but not allowed. Mistake: returning 401 instead of 403 or vague reason.- 404 Not Found — Use: unknown resource or route. Mistake: using 404 for auth-hidden resources without explanation.- 409 Conflict — Use: concurrency/version conflict or duplicate unique constraint. Mistake: using 400 or 422 instead.- 422 Unprocessable Entity — Use: semantic validation (business rules) though syntactically valid. Mistake: mixing 400 and 422 inconsistently.- 429 Too Many Requests — Use: rate limit exceeded; include Retry-After. Mistake: not providing Retry-After or global 503s instead.

**5xx — Server errors**- 500 Internal Server Error — Use: unexpected server failure. Mistake: overusing 500 for predictable failures; no correlation id.- 502 Bad Gateway — Use: upstream gateway/proxy error. Mistake: masking upstream details without guidance.- 503 Service Unavailable — Use: maintenance or transient overload; include Retry-After. Mistake: returning 503 without ETA or using it for auth issues.

For each, include structured error body (code, message, details, correlation_id, retry_after when relevant) — improves DX, observability and reduces support load.

Unlock Full Question Bank

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

Join thousands of developers preparing for their dream job.