Interview questions

Interview questions (with the counter-questions you'll get)

Q1. What makes a good API?

They're testing: design taste.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** A clear, documented contract designed around client needs; consistent naming, units and error formats; safe evolution through additive changes and versioning; cursor pagination for large lists; correct status codes; authentication and per-resource authorisation; rate limits; and idempotency for writes so clients can retry safely.
3
4**Counter-questions:**
5- *"How do you document it?"* → OpenAPI (or .proto) as the source of truth, with generated docs, clients and contract tests.
6
7**Trap:** talking only about URL naming.

Q2. REST vs gRPC vs GraphQL: when would you use each?

They're testing: trade-offs.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** REST for public and browser-facing APIs: universal, cacheable, easy to debug. gRPC for internal service-to-service calls: typed, compact binary over HTTP/2, with streaming. GraphQL when many clients need different shapes of related data in one round trip, at the cost of harder caching and the need for query cost limits.
3
4**Counter-questions:**
5- *"Can you mix them?"* → Commonly: gRPC inside, REST or GraphQL at the edge through a gateway.
6
7**Trap:** declaring one style best for everything.

Q3. What does idempotent mean, and which HTTP methods are idempotent?

They're testing: precise definitions.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** An operation is idempotent if doing it many times has the same effect as doing it once. In HTTP, GET, HEAD, OPTIONS, PUT and DELETE are idempotent; POST is not, and PATCH isn't guaranteed to be. Safe methods (GET, HEAD, OPTIONS) don't change state at all.
3
4**Counter-questions:**
5- *"Is DELETE idempotent if the second call returns 404?"* → Yes: the effect on the server is the same (it's gone); only the response differs.
6
7**Trap:** confusing idempotent with safe.

Q4. How do you prevent double charges when clients retry?

They're testing: the core idempotency design.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** The client sends an idempotency key per intended payment and reuses it on retries. The server atomically claims the key, processes the charge, and stores the response; repeats return the stored response; concurrent repeats get 409; a mismatched body gets an error; keys expire after a period like 24 hours. Pass the key through to the payment provider too.
3
4**Counter-questions:**
5- *"Where's the race?"* → Between checking for the key and saving it; claim it with a unique insert before doing the work.
6
7**Trap:** de-duplicating by comparing amounts and timestamps.

Q5. Offset vs cursor pagination?

They're testing: practical API design.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** Offset is simple and allows jumping to a page, but shows duplicates or skips when data changes and gets slow for deep pages because the database skips rows. Cursor pagination returns items after the last one seen, using the index, so it's stable and fast at any depth, but you can't jump to arbitrary pages.
3
4**Counter-questions:**
5- *"What's in the cursor?"* → An opaque encoding of the sort key plus a unique tie-breaker like the ID.
6
7**Trap:** using offset for an infinite feed.

Q6. How do you version an API without breaking clients?

They're testing: evolution.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** Make additive, backward-compatible changes by default and require clients to ignore unknown fields. For breaking changes, introduce a new version (URL or header), run both, translate old requests internally, measure usage, and announce a sunset date before removing the old one.
3
4**Counter-questions:**
5- *"What counts as breaking?"* → Removing or renaming fields, changing types or meaning, new required inputs, changed error codes.
6
7**Trap:** changing a field's type "because only one client uses it".

Q7. Which errors should a client retry?

They're testing: reliability judgement.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** Timeouts, connection errors, 429 (after Retry-After), and 5xx such as 502, 503 and 504, with exponential backoff and jitter, a cap on attempts, and an overall deadline. Not 4xx errors like 400, 401, 403, 404, 409 or 422. Non-idempotent requests only with an idempotency key.
3
4**Counter-questions:**
5- *"What's a retry storm?"* → Many clients or layers retrying at once, multiplying load on a struggling service; prevent with jitter, budgets, single-layer retries and circuit breakers.
6
7**Trap:** retrying everything three times at every layer.

Q8. How do you secure a webhook endpoint?

They're testing: security in practice.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** Verify an HMAC signature of the timestamp and body using a shared secret, compare in constant time, reject old timestamps to stop replays, use HTTPS, de-duplicate by event ID, and treat the payload as a hint: for critical actions, fetch the current state from the provider's API.
3
4**Counter-questions:**
5- *"Why include the timestamp in the signature?"* → So an attacker can't replay an old, validly signed request later.
6
7**Trap:** relying on a secret URL alone.

Q9. What's the difference between authentication and authorisation in an API?

They're testing: security basics.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** Authentication establishes who the caller is: an API key for a program, an access token for a user. Authorisation decides what that caller may do, checked on every request against the specific resource. Many breaches come from authenticated users accessing other users' objects by changing an ID.
3
4**Counter-questions:**
5- *"Where do you check it?"* → In the service that owns the data, not only at the gateway.
6
7**Trap:** "the gateway checks the token, so we're safe".

Q10. Design an API for a payment provider (like Stripe).

They're testing: putting the chapter together.

Think about your answer first, then open it.

reveal

1Show the strong answer, counter-questions and trap
2**Strong answer:** REST resources (charges, refunds, customers) with dated versioning; secret API keys per merchant, stored hashed, with test and live modes; idempotency keys on every POST, stored with responses for at least 24 hours; integer amounts in the smallest currency unit; Problem Details errors with machine codes; cursor pagination; per-key rate limits returning 429; and signed, retried, de-duplicated webhooks for asynchronous events.
3
4**Counter-questions:**
5- *"How do merchants know a payment finished if the webhook never arrives?"* → They can poll the charge, and should reconcile periodically by listing recent charges.
6
7**Trap:** forgetting asynchronous completion and webhooks.
8
9---
10
11## Practice coverage
12
13Every section in this chapter is tested at least once.
14
15| Section | Tested by |
16|---|---|
17| 24.1 API contract | Level 5.1, Q1 |
18| 24.2 API styles | Level 5.1, Q2 |
19| 24.2.1 REST | Level 1B.1, Level 1B.4, Q3 |
20| 24.2.2 gRPC | Level 5.1, Q2 |
21| 24.2.3 GraphQL | Level 5.1, Q2 |
22| 24.3 Versioning | Q6 |
23| 24.4 Pagination | Level 2.2, Level 3.2, Level 5.2, Q5 |
24| 24.5 Errors and status codes | Level 1A, Level 3.3, Level 5.3, Q7 |
25| 24.6 API auth | Level 1A.2, Level 1A.3, Level 3.4, Q9 |
26| 24.7 Double charge | Level 1B.2, Level 2.1, Q4 |
27| 24.8 Idempotency keys | Level 2.3, Level 3.1, Level 4, Level 5.4, Q4, Q10 |
28| 24.9 Safe retries | Level 1B, Level 2.4, Level 2.5, Q7 |
29| 24.10 Webhooks | Level 3.5, Level 5.5, Q8 |
30
31---

24. APIs and Idempotency