API design interview: framework, questions and common pitfalls

A framework for API design rounds

1. Clarify the use cases and clients (mobile, web, partners, internal services).
2. Identify resources and their relationships.
3. Define endpoints or methods, with request and response shapes.
4. Specify errors and status codes.
5. Add pagination, filtering and sorting for collections.
6. Handle idempotency, versioning, authentication and rate limits.
7. Discuss REST versus GraphQL versus gRPC for this case.

Resource modelling and HTTP semantics

Model nouns as resources and use HTTP methods for verbs: GET to read, POST to create, PUT to replace, PATCH to update partially, DELETE to remove. Nest only where ownership is real (/users/42/orders), and keep URLs plural and consistent. GET must be safe — no side effects — and GET, PUT and DELETE should be idempotent, meaning repeating them leaves the same state.

Pagination

Offset pagination (?offset=40&limit=20) is simple but slow on large tables and unstable when rows are inserted. Cursor pagination returns an opaque cursor pointing after the last item, which is stable and efficient for feeds and large collections. Mention both and pick cursor for anything that grows quickly or changes often.

Idempotency and retries

Networks fail after a server has acted, so clients retry. For non-idempotent operations such as creating a payment, accept an Idempotency-Key header: the server stores the key with the result and returns the same result for repeats instead of charging twice. This is one of the most valued points in API interviews because it shows production experience.

Versioning, auth and limits

• Versioning: a path prefix (/v1/) is explicit and simple; header-based versioning keeps URLs clean. Add fields freely; never remove or repurpose them without a new version.
• Authentication: OAuth 2.0 with short-lived tokens for user-facing access; API keys for server-to-server, kept secret and rotatable.
• Rate limiting: per client or key, with 429 and Retry-After, and limit headers so clients can back off.
• Errors: a consistent error body with a machine-readable code, a human message and a request ID.

Worked example: a URL shortener API

POST /v1/links with {"url": "…", "alias": optional} returns 201 and {"code": "x7Kp2", "short_url": "…"}. A duplicate custom alias returns 409. GET /v1/links/{code} returns metadata to the owner; the public redirect is GET /{code} returning 301 or 302 — 302 if you need every click to reach your servers for analytics. GET /v1/links lists the caller's links with cursor pagination. Authentication by API key; rate limit link creation per key. Discuss whether to accept an Idempotency-Key on creation so retries don't create duplicates. See REST API interview questions.

REST, GraphQL or gRPC?

REST is the default for public APIs: cacheable, widely understood, simple tooling. GraphQL suits clients that need flexible, nested data from many sources, at the cost of harder caching and query-cost control. gRPC suits internal service-to-service calls where performance and strict contracts matter. Choosing one with a reason scores better than defaulting. See GraphQL interview questions.

Practising

Design three APIs aloud — a payments API, a chat API and a file-upload API — covering every step of the framework. A free AI interview assistant such as CoPilot Interview can play the interviewer and push on edge cases like retries and partial failures.

Disclosure: CoPilot Interview is our product, so weigh what we say about it accordingly. Everything else on this page applies whichever tool you use, or none.

Frequently asked questions

What is asked in an API design interview?

You design the interface for a service: resources and endpoints, request and response formats, errors and status codes, plus pagination, idempotency, versioning, authentication and rate limiting.

What is idempotency in API design?

An operation is idempotent if repeating it has the same effect as doing it once. For non-idempotent creates, such as payments, an Idempotency-Key header lets servers return the original result to retried requests.

Should I use cursor or offset pagination?

Cursor pagination is more efficient and stable for large or frequently changing collections; offset is simpler for small, static ones. Mention both and justify your choice.

How should I version an API?

A path prefix such as /v1/ is the most explicit. Add fields without a new version, but introduce a new version before removing or changing the meaning of existing fields.