How to assess · For hiring teams
How to Assess API Design Skills When Hiring
The test formats that actually work for API Design, what a strong answer looks like, sample questions and a scoring rubric you can use as-is.
The short answer
Assess API Design with a task, not a conversation: design an api from a brief, review a flawed api, ai-scored assessment (e.g. cohesyve) or evolution scenario. Score it against written criteria you fix before you see any submissions, and weight the criteria that the role actually depends on.
- Models resources around consumer needs, not database tables
- Is consistent: naming, pagination, filtering, error shape and status codes follow one pattern
- Returns errors that a client can act on, with a stable code and a human-readable message
- Designs for evolution: additive changes by default, versioning strategy decided up front, deprecation with notice
Paste a job description; Cohesyve generates a role-specific assessment and rubric. Ten candidates free, no card.
An API is a contract that outlives the code behind it, which makes API design one of the highest-leverage engineering skills and one of the least tested. A poorly designed endpoint costs every consumer, forever, or until a painful migration. The skill is not knowing REST conventions; it is modelling resources so they match how consumers think, handling errors so clients can act on them, and evolving the contract without breaking anyone. This page covers how to assess API design for backend and platform roles: resource modelling, consistency, error handling, versioning and evolution, and the documentation that makes an API usable.
Why API Design is worth testing
API design mistakes are expensive precisely because they are hard to undo. An endpoint that leaks internal structure, returns errors nobody can parse, or changes shape without warning creates work for every team that depends on it. Testing shows whether a candidate designs for consumers and for change, and that determines whether the platform the team builds is something others want to use.
What strong API Design looks like
- Models resources around consumer needs, not database tables
- Is consistent: naming, pagination, filtering, error shape and status codes follow one pattern
- Returns errors that a client can act on, with a stable code and a human-readable message
- Designs for evolution: additive changes by default, versioning strategy decided up front, deprecation with notice
- Handles authentication, rate limiting and idempotency as part of the design
- Documents the contract in a machine-readable form and keeps it accurate
- Considers the consumer's first integration: how quickly can someone make a successful call
Ways to assess API Design
Design an API from a brief
Describe a small domain — bookings with availability, or invoices with line items and payments — and ask for the resources, endpoints, error handling and a plan for one likely change. Forty-five to sixty minutes.
Pros
Cons
Best for Mid and senior backend engineers.
Review a flawed API
Provide an API specification with inconsistent naming, database ids leaking, errors as free text, a breaking change in a minor version and no pagination on a list. Ask for review comments and priorities.
Pros
Cons
Best for Senior and lead roles.
AI-scored assessment (e.g. Cohesyve)
Generate an API design task from the job description — a domain to model, a spec to review, a migration to plan — with a rubric. Each candidate receives a different variant; the written design and reasoning are scored.
Pros
Cons
Best for Screening a pool before design interviews.
Evolution scenario
Present an existing API with consumers and a required change that would break them. Ask how they would make it.
Pros
Cons
Best for Engineers owning public or widely used APIs.
Cohesyve
Run a API Design assessment on your next opening
Cohesyve generates a unique API Design task per candidate from your job description, with the scoring rubric attached. Questions are different for every applicant, so they cannot be shared or looked up.
What to test
Resource modelling
Whether the API matches how consumers think.
Consistency and errors
Whether the API is predictable.
Evolution
Whether the contract can change safely.
Operability and documentation
Whether the API can be run and used.
Sample API Design questions
What should an error response contain?
EntryLook for A stable machine-readable code, a human message, and enough detail to act; consistent shape; the right status code.
Should a "cancel order" be a DELETE, a PATCH on status, or a POST to an action? Justify.
MidLook for Considers semantics, side effects and consumer expectations; any answer with clear reasoning is acceptable.
You need to rename a field that hundreds of clients use. Plan it.
MidLook for Add the new field, keep the old one, announce a deprecation window, monitor usage, remove after clients migrate.
How do you make a payment-creation endpoint safe to retry?
MidLook for Idempotency keys, stored results, and what happens on a duplicate with different data.
Design the pagination for a resource with millions of rows that changes constantly.
SeniorLook for Cursor-based over offset, stable ordering, handling of inserts during paging, and what the client can rely on.
Red flags
- Exposes database structure directly
- Free-text errors with 200 status
- No plan for change; "we will version it later"
- Inconsistent naming across endpoints
- Has never consumed their own API as a client
Scoring rubric
| Criterion | Weight | What strong looks like |
|---|---|---|
| Modelling | 30% | Resources match consumer needs and hide internals. |
| Consistency and errors | 25% | One pattern everywhere; errors are actionable. |
| Evolution | 25% | Changes are additive; breaking changes have a path. |
| Operability and documentation | 20% | Idempotent, rate-limited, documented for a first call. |
Mistakes hiring teams make
- Testing REST trivia rather than modelling judgement
- Not including an evolution scenario — the hardest part
- Accepting a design with no error shape
- Rewarding cleverness over consistency
- Skipping the consumer's perspective entirely
Roles that need API Design
Common questions
REST, GraphQL or gRPC — which should the assessment use?
Whichever the role uses. Modelling, consistency and evolution matter in all three; the transport is secondary. If the role is undecided, let the candidate choose and explain.
What is the best single API design question?
Ask them to plan renaming a widely used field. It tests evolution thinking, consumer empathy and process in one answer.
How long should an API design assessment take?
Forty-five to sixty minutes for a design from a brief. A written specification as a take-home should be capped at two hours.
Should junior developers be assessed on API design?
Lightly. Consistent naming, sensible status codes and a proper error shape are fair expectations. Evolution and versioning strategy are senior skills.
Cohesyve · Skill assessments for hiring
Test API Design before the first interview
Generate a role-specific API Design assessment from your job description and see who can do the work before you spend interview time on them.
1,500+
assessments completed
50%
faster time-to-hire
90%
completion rate
5 min
from JD to assessment
No credit card · 10 free candidates · Plans sized to your hiring volume
From the blog