Java REST and API design
The contract other teams build against. Most of the difficulty is not in the happy path but in versioning, errors and repeated calls.
5 concepts · 16 interview questions
What this topic covers
Every concept in rest and api design, and the questions each one gets asked as. Where a question links, it has a full write-up.
Resources, verbs and status codes
A REST API models resources and uses the HTTP method to say what is being done to them. The method decides what a client, a proxy and a retry are allowed to assume.
- What makes an API RESTful, beyond using HTTP?
- Which HTTP methods are safe, and which are idempotent?
- When would you return 400 versus 422, and 401 versus 403?
- Should a failed business rule be a 200 with an error body?
Idempotency and retries
A network client cannot tell a lost response from a lost request, so it retries. Anything that moves money or creates a record needs a way to recognise the repeat.
- How do you make a POST endpoint safe to retry?
- Where should the idempotency key come from, and how long do you keep it?
- What happens when a retry arrives while the first request is still running?
Versioning and compatibility
Once another team depends on your response shape, changing it is a deployment problem rather than a code change. Additive changes are cheap; removals and renames are not.
- How do you version an API, and which approach would you pick?
- Which changes are backwards compatible and which are not?
- How do you remove a field that a client might still read?
Pagination, filtering and payload size
An endpoint that returns everything works until the data grows. Pagination style decides whether results stay stable while pages are being read.
- Offset pagination or cursor pagination?
- How do you stop an endpoint returning a hundred megabytes?
- Should the API let a client choose which fields come back?
Error contracts
Errors are part of the contract and are usually designed last. A caller needs to know what failed, whether retrying will help, and what to show a user.
- What belongs in an error response?
- How do you avoid leaking internals in an error?
- What is RFC 7807 problem detail, and is it worth adopting?