API Design Interview Questions and Answers

Sample questions

A few questions from each level with the correct answer and an explanation.

API Design · Junior

1. What is a REST API, in practical terms?

   Correct answer: An HTTP API organized around resources identified by URLs, manipulated with standard methods like GET, POST, PUT, PATCH and DELETE

   REST is an architectural style described by Roy Fielding. Most 'REST APIs' follow its main ideas: resources, uniform interface, statelessness and cacheability.

2. Which URL design follows common REST conventions?

   Correct answer: GET /users/42/orders

   URLs name resources (nouns, usually plural); the HTTP method says what to do. Verbs in paths are an RPC style.

3. What does 'stateless' mean for a REST API?

   Correct answer: Each request carries everything the server needs (e.g. auth token); the server doesn't rely on session state from previous requests

   Statelessness makes horizontal scaling easy: any instance can handle any request.

4. Which HTTP method should create a new resource in a collection, like a new order?

   Correct answer: POST /orders

   The server assigns the ID and usually responds with 201 Created and a Location header pointing to the new resource.

API Design · Middle

1. How would you model 'cancel an order' in a REST API?

   Correct answer: As a state change (PATCH /orders/42 with {status: "cancelled"}) or a custom action (POST /orders/42:cancel or /orders/42/cancellation), documented consistently

   Cancelling usually keeps the order for history and may have business rules. A dedicated action makes those rules explicit; GET must never change state.

2. When should a relationship be its own resource, like /users/42/memberships?

   Correct answer: When it has its own data or lifecycle (role, joined date, approval), not just a link between two items

   Treating a membership as a resource gives you natural create, update and delete operations on it.

3. What does JSON Patch (RFC 6902) look like?

   Correct answer: A list of operations like { "op": "replace", "path": "/email", "value": "a@b.c" }

   Operations include add, remove, replace, move, copy and test. It's precise for arrays but more complex for clients.

4. How can a REST API let clients load related resources in one request?

   Correct answer: With an expansion parameter like ?include=author,comments (JSON:API) or ?expand=customer

   Expansion avoids chatty clients while keeping default responses small. Limit how deep and how many relations can be included.

API Design · Senior

1. How do you choose between REST, GraphQL and gRPC for a new system?

   Correct answer: By consumers and constraints: REST for public, cacheable resource APIs; GraphQL for varied UI data needs; gRPC for internal low-latency service calls with typed contracts

   Many systems mix them: gRPC between services, a GraphQL or REST BFF for clients, and REST for public partners.

2. What is an 'API as a product' mindset?

   Correct answer: Treating the API's consumers as customers: stable contracts, good docs, onboarding, versioning policy, support and usage metrics

   Internal APIs benefit too: other teams are customers whose productivity depends on your design.

3. Why establish API governance (style guide, reviews, linting) in an organization with many teams?

   Correct answer: So APIs feel like one platform: consistent naming, errors, pagination and auth, which lowers integration cost for every consumer

   Automate what you can (Spectral rules, breaking-change checks) and keep human review for modeling decisions.

4. How do Hyrum's Law and 'be conservative in what you send' interact in API evolution?

   Correct answer: Every observable behavior gets depended on, so expose as little as needed, document guarantees explicitly and avoid accidental contracts like field order

   Even error message text, default sort orders or response timing can become something clients rely on.

Combined quizzes with this topic

Questions from several topics at once - just like an interview for a specific role.