Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 4 · Lesson 26 · 4 min read

API Design Case Study: Designing a Real Product API

On this page
  1. The problem: an API for a team task manager
  2. Choosing REST for the public API
  3. Resources and URL design
  4. Payload design
  5. Authentication with OAuth and object-level authorization
  6. Pagination, errors, idempotency and rate limits
  7. Notifying integrations with webhooks
  8. Versioning, deprecation and documentation
  9. What a strong API design answer includes
  10. 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.

The task manager's API: a public REST surface with OAuth scopes and webhooks for integrations, alongside the first-party apps, with tasks nested under projects in workspaces.
The task manager's API: a public REST surface with OAuth scopes and webhooks for integrations, alongside the first-party apps, with tasks nested under projects in workspaces.

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

Code
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).
  • PATCH for partial updates with an allow-list of fields (Day 24); If-Match with ETags so two people editing the same task don't overwrite each other (Day 5).

Payload design

JSON
{
  "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, limit capped at 100 (Day 7).
  • Problem details for every error, with field-level validation errors and request IDs (Day 8).
  • Idempotency-Key accepted on every POST, 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-After on 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 Deprecation and Sunset headers, and usage tracked per client before anything is removed.

What a strong API design answer includes

  1. A clear choice of style, justified by who the clients are.
  2. Consistent resources, methods and status codes.
  3. Authorization at the object level, not just authentication.
  4. Safe retries, pagination and rate limits designed in from the start.
  5. A notification mechanism for integrations.
  6. 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.