Full-stack Developer interview question
How do you design a clear API?
A clear API models domain resources and operations consistently, validates inputs, uses predictable status and error formats, supports pagination and idempotency where needed, and evolves through an explicit compatibility policy.
Direct answer
What a strong answer covers
How it works
A clear API is predictable: resources are nouns with consistent naming, operations map to HTTP methods with their standard semantics, and the same shape of error body appears everywhere with a machine-readable code and a human message. Inputs are validated at the edge with precise 4xx responses. Lists paginate with cursors, filters and sorting are explicit parameters, writes that clients retry accept idempotency keys, and timestamps use one format in UTC. The contract is written down in OpenAPI before the code, reviewed by a consumer, and evolves under a stated compatibility policy.
Example
GET /orders?status=open&cursor=abc returns a page of orders and a next cursor; POST /orders with an Idempotency-Key header creates one and returns 201 with a Location header; a validation failure returns 422 with a list of field errors, and every error carries the same envelope with code, message, and request_id so the frontend can render it uniformly.
Common mistakes
- Using POST for everything and encoding the action in the body.
- Returning 200 with an error object inside the payload.
- Exposing database column names and internal IDs directly as the public contract.
A useful answer structure
Answer from your own work.
Do not memorise a script: use only examples you can explain honestly in follow-up questions.
Open the desktop workspace and rehearse a clear answer in your own words.