API Design Case Study: Designing a Real Product API
On this page
- The problem: an API for a team task manager
- Choosing REST for the public API
- Resources and URL design
- Payload design
- Authentication with OAuth and object-level authorization
- Pagination, errors, idempotency and rate limits
- Notifying integrations with webhooks
- Versioning, deprecation and documentation
- What a strong API design answer includes
- Check yourself
The problem: an API for a team task manager
Try it yourself before reading the walkthrough. A team task manager needs an API for:
- Its own web and mobile apps.
- Third-party integrations (a Slack bot, a time tracker) acting on behalf of users.
- Workspaces containing projects; projects containing tasks; tasks with assignees, due dates, status and comments.
- Integrations want to know when tasks change.
Decide: REST or GraphQL, URLs, authentication, authorization, pagination, errors, retries, versioning, notifications and docs.
Choosing REST for the public API
Third parties use many languages and tools, need stable, cacheable endpoints and webhooks, and their operations are clear (Day 20). REST with OpenAPI. The first-party apps could use a GraphQL layer or BFF later (Day 21); the public API comes first.
Resources and URL design
GET /v1/workspaces/{workspaceId}/projects
GET /v1/projects/{projectId}/tasks?status=open&assigneeId=u_7&sort=dueDate&limit=20&after=<cursor>
POST /v1/projects/{projectId}/tasks
GET /v1/tasks/{taskId}
PATCH /v1/tasks/{taskId}
DELETE /v1/tasks/{taskId}
POST /v1/tasks/{taskId}/comments
POST /v1/tasks/{taskId}/completion # an action modeled as a resource- Shallow nesting (Day 3): tasks are created and listed within a project, but have a top-level URL, since integrations store task IDs.
- Filtering and sorting through query parameters, on indexed fields only (Day 7).
PATCHfor partial updates with an allow-list of fields (Day 24);If-Matchwith ETags so two people editing the same task don't overwrite each other (Day 5).
Payload design
{
"id": "tsk_8Fz2",
"projectId": "prj_31",
"title": "Draft launch email",
"status": "open",
"assigneeId": "u_7",
"dueDate": "2026-10-20",
"createdAt": "2026-10-11T09:12:00Z",
"updatedAt": "2026-10-11T09:12:00Z"
}String IDs with prefixes (easy to recognize in logs), ISO dates, lowercase enum values, a top-level object for every response (Day 5).
Authentication with OAuth and object-level authorization
- OAuth 2.0 authorization code with PKCE for integrations acting for users, with scopes such as
tasks:read,tasks:write,comments:write(Day 12). - Short-lived JWT access tokens with refresh tokens.
- Every handler checks scope, workspace membership, and object access in the query itself:
WHERE task.id = $1 AND workspace_id IN (viewer's workspaces). Tasks in workspaces the user can't see return 404 (Day 13).
Pagination, errors, idempotency and rate limits
- Cursor pagination everywhere,
limitcapped at 100 (Day 7). - Problem details for every error, with field-level validation errors and request IDs (Day 8).
Idempotency-Keyaccepted on everyPOST, so a Slack bot retrying after a timeout doesn't create duplicate tasks (Day 10).- Rate limits per OAuth client and per user, with
Retry-Afteron 429 (Day 11).
Notifying integrations with webhooks
Integrations subscribe to events such as task.created, task.updated, task.completed and comment.created. Thin payloads with IDs, signed with HMAC and a timestamp, retried with backoff, and deduplicated by event ID (Day 25).
Versioning, deprecation and documentation
- URL major version (
/v1), with additive changes within it (Days 6 and 23). - OpenAPI spec in the repository, linted and checked for breaking changes in CI, with generated docs and SDKs (Day 22).
- Deprecations announced with
DeprecationandSunsetheaders, and usage tracked per client before anything is removed.
What a strong API design answer includes
- A clear choice of style, justified by who the clients are.
- Consistent resources, methods and status codes.
- Authorization at the object level, not just authentication.
- Safe retries, pagination and rate limits designed in from the start.
- A notification mechanism for integrations.
- A plan for change: versioning, deprecation and a machine-readable contract.
Check yourself
Integrations store and reference task ids directly. A top-level URL like /tasks/123 avoids requiring the full parent chain for every call, and keeps working if a task moves to another project.
Integrations retry after timeouts and network errors, not knowing whether the first request succeeded. The key makes a retry return the original task instead of creating a duplicate, which users would otherwise have to clean up by hand.
It avoids confirming that the task exists, which would leak information about other workspaces, such as their size or activity. From the user's point of view, a task they can't access simply isn't there.
PATCH requires If-Match with the task's ETag; the second, now stale, request gets 412 and must re-read the task before trying again.