Resource Design Patterns · Lesson 08

Capstone: build a complete mock API

Every pattern from this module — resource naming, standard methods, custom methods, field masks, long-running operations, batch, soft delete, validation — converges here. Follow this lesson and you will have a complete, runnable Tasks API specification you can serve as a mock today.

The API we are building: Tasks

The Tasks API manages work items inside projects. A project is the parent resource; a task is the child. Every pattern from this module is exercised on one or both of these resources. The result is not a toy — it is the kind of spec you would present in a design review or check into a company API registry.

Resource hierarchy (from rdp-01):

Collection:  /v1/projects
Resource:    /v1/projects/{project}

Collection:  /v1/projects/{project}/tasks
Resource:    /v1/projects/{project}/tasks/{task}

Task resource fields:

{
  "name":         "projects/{project}/tasks/{task}",  // server-assigned, immutable
  "title":        "string",                           // required, 1–500 chars
  "notes":        "string",                           // optional
  "status":       "OPEN | IN_PROGRESS | DONE",
  "due_time":     "RFC 3339 timestamp | null",
  "assignee":     "users/{user} | null",
  "labels":       ["string"],
  "completed":    false,                              // set by :complete
  "create_time":  "RFC 3339 timestamp",               // server-set, immutable
  "update_time":  "RFC 3339 timestamp",               // server-set on every write
  "delete_time":  "RFC 3339 timestamp | null",        // soft-delete sentinel
  "expire_time":  "RFC 3339 timestamp | null"         // expiry after soft-delete
}

Complete endpoint table

Every endpoint in the API. Pattern links point back to the lesson that introduced each concept.

Architecture diagram: how the patterns layer

Step-by-step: assemble the API

1. Resource model & URL layout — establish the naming hierarchy (rdp-01). Every subsequent endpoint is a path under this hierarchy.
2. Standard CRUD methods — wire up GET (get + list), POST (create), PUT (update), PATCH (partial update), DELETE (soft-delete) (rdp-02).
3. Custom method :complete — add the task completion business action as a POST to a verb-suffix path (rdp-03).
4. PATCH with update_mask — implement partial updates that only touch named fields, preventing overwrite races (rdp-04).
5. Long-running :exportTasks — wrap the slow export in a Long-Running Operation that returns immediately with a polling handle (rdp-05).
6. batchGet — add a single-round-trip multi-fetch to reduce client-side N+1 calls (rdp-06).
7. Soft delete + undelete + validate_only — make DELETE reversible, add :expunge for hard deletion, and add the dry-run flag to CREATE (rdp-07).
8. Pagination + filtering on List — add page_size/page_token and a filter query parameter to List.
9. Error shape — standardize all errors to a single JSON envelope.
10. Auth & versioning notes — document the Bearer-token expectation and the /v1/ version prefix (see sec-08, rel-01).

Compact request/response for every endpoint

Each block shows the minimum viable request and a representative success response. Error shapes are consolidated at the end.

1 — List tasks (pagination + filtering)

GET /v1/projects/proj_42/tasks?page_size=2&filter=status%3DOPEN&show_deleted=false
Authorization: Bearer <token>

200 OK
{
  "tasks": [
    { "name": "projects/proj_42/tasks/task_01", "title": "Update onboarding docs", "status": "OPEN", "create_time": "2026-05-01T10:00:00Z", "update_time": "2026-05-01T10:00:00Z" },
    { "name": "projects/proj_42/tasks/task_02", "title": "Write API design doc", "status": "OPEN", "create_time": "2026-05-02T09:00:00Z", "update_time": "2026-05-02T09:00:00Z" }
  ],
  "next_page_token": "eyJvZmZzZXQiOjJ9"
}

2 — Create task

POST /v1/projects/proj_42/tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "task": {
    "title":    "Prepare quarterly report",
    "due_time": "2026-07-01T17:00:00Z",
    "assignee": "users/alice",
    "labels":   ["finance", "q2"]
  }
}

201 Created
{
  "name":        "projects/proj_42/tasks/task_77",
  "title":       "Prepare quarterly report",
  "status":      "OPEN",
  "due_time":    "2026-07-01T17:00:00Z",
  "assignee":    "users/alice",
  "labels":      ["finance", "q2"],
  "completed":   false,
  "create_time": "2026-06-20T14:00:00Z",
  "update_time": "2026-06-20T14:00:00Z"
}

3 — Get task

GET /v1/projects/proj_42/tasks/task_77
Authorization: Bearer <token>

200 OK
{ /* same body as Create response above */ }

4 — PATCH with update_mask (partial update)

PATCH /v1/projects/proj_42/tasks/task_77
Authorization: Bearer <token>
Content-Type: application/json

{
  "update_mask": "title,due_time",
  "task": {
    "title":    "Prepare Q2 quarterly report",
    "due_time": "2026-07-05T17:00:00Z"
  }
}

200 OK
{
  "name":        "projects/proj_42/tasks/task_77",
  "title":       "Prepare Q2 quarterly report",
  "due_time":    "2026-07-05T17:00:00Z",
  "assignee":    "users/alice",
  // ... other fields unchanged
  "update_time": "2026-06-20T14:05:00Z"
}

5 — Custom method :complete

POST /v1/projects/proj_42/tasks/task_77:complete
Authorization: Bearer <token>
Content-Type: application/json

{}

200 OK
{
  "name":        "projects/proj_42/tasks/task_77",
  "status":      "DONE",
  "completed":   true,
  "update_time": "2026-06-20T14:10:00Z"
}

6 — Long-running :exportTasks

POST /v1/projects/proj_42/tasks:exportTasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "format": "CSV",
  "filter": "status=DONE"
}

202 Accepted
{
  "name":     "operations/op_export_7f3a",
  "done":     false,
  "metadata": { "progress_percent": 0 }
}

# Poll until done
GET /v1/operations/op_export_7f3a

200 OK (completed)
{
  "name":     "operations/op_export_7f3a",
  "done":     true,
  "response": {
    "download_url": "https://storage.example.com/exports/proj_42_tasks.csv",
    "row_count":    142
  }
}

7 — batchGet

POST /v1/projects/proj_42/tasks:batchGet
Authorization: Bearer <token>
Content-Type: application/json

{
  "names": [
    "projects/proj_42/tasks/task_01",
    "projects/proj_42/tasks/task_77"
  ]
}

200 OK
{
  "tasks": [
    { "name": "projects/proj_42/tasks/task_01", "title": "Update onboarding docs", "status": "OPEN" },
    { "name": "projects/proj_42/tasks/task_77", "title": "Prepare Q2 quarterly report", "status": "DONE" }
  ]
}

8 — Soft delete, :undelete, :expunge

# Soft-delete
DELETE /v1/projects/proj_42/tasks/task_77
200 OK → { "name":..., "delete_time":"2026-06-20T15:00:00Z", "expire_time":"2026-07-20T15:00:00Z" }

# Restore
POST /v1/projects/proj_42/tasks/task_77:undelete
200 OK → { "name":..., "delete_time":null, "expire_time":null }

# Hard-delete (elevated permission)
POST /v1/projects/proj_42/tasks/task_77:expunge
200 OK → {}

9 — validate_only dry-run

POST /v1/projects/proj_42/tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "validate_only": true,
  "task": { "title": "Safe to create?", "assignee": "users/alice" }
}

200 OK → {} (nothing created; validation passed)

10 — Consistent error shape

# Every error uses this envelope
{
  "error": {
    "code":    400,
    "status": "INVALID_ARGUMENT",
    "message": "Field 'title' is required.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "field_violations": [
          { "field": "title", "description": "must not be empty" }
        ]
      }
    ]
  }
}

HTTP status maps to code; status is the canonical Google RPC status name (see AIP-193). The details array carries structured machine-readable context.

Stand up the mock

You now have a complete spec. The fastest path to a running mock is to serve pre-written JSON files, one per endpoint. A slightly richer option is to generate a live mock from an OpenAPI document using Prism. Both approaches are described below.

Option A — Static JSON files + any HTTP server

Create one JSON file per unique response. Map request paths to files using the server's routing rules. This works with python -m http.server, npx serve, or any static host.

Limitation: static files cannot distinguish POST from GET, so all method-differentiated responses (create vs list) need a more capable router. For quick demos this is fine; for contract testing, use Option B.

Option B — Prism from an OpenAPI skeleton

Prism reads an OpenAPI 3.x document and serves a mock that validates requests and returns example responses. Install it and point it at the skeleton file.

Minimal OpenAPI skeleton

This skeleton covers the List and Create endpoints. Extend it with the same pattern for every other endpoint in the table above.

openapi: "3.1.0"
info:
  title: Tasks API
  version: "1.0.0"
servers:
  - url: https://api.example.com
paths:
  /v1/projects/{project}/tasks:
    get:
      summary: List tasks
      parameters:
        - { name: project, in: path, required: true, schema: { type: string } }
        - { name: page_size, in: query, schema: { type: integer, default: 20 } }
        - { name: page_token, in: query, schema: { type: string } }
        - { name: filter, in: query, schema: { type: string } }
        - { name: show_deleted, in: query, schema: { type: boolean, default: false } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ListTasksResponse" }
    post:
      summary: Create task
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateTaskRequest" }
      responses:
        "201":
          description: Task created
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Task" }
components:
  schemas:
    Task:
      type: object
      properties:
        name:        { type: string, readOnly: true }
        title:       { type: string }
        notes:       { type: string }
        status:      { type: string, enum: [OPEN, IN_PROGRESS, DONE] }
        due_time:    { type: string, format: date-time, nullable: true }
        assignee:    { type: string, nullable: true }
        labels:      { type: array, items: { type: string } }
        completed:   { type: boolean }
        create_time: { type: string, format: date-time, readOnly: true }
        update_time: { type: string, format: date-time, readOnly: true }
        delete_time: { type: string, format: date-time, nullable: true, readOnly: true }
        expire_time: { type: string, format: date-time, nullable: true, readOnly: true }
    CreateTaskRequest:
      type: object
      properties:
        validate_only: { type: boolean, default: false }
        task: { $ref: "#/components/schemas/Task" }
    ListTasksResponse:
      type: object
      properties:
        tasks:           { type: array, items: { $ref: "#/components/schemas/Task" } }
        next_page_token: { type: string }

Sources & further reading

• Google AIP-1 — AIP overview and purpose
• Google AIP-193 — Errors
• OpenAPI Specification 3.1.0
• Stoplight Prism — open-source API mock server
• rdp-01: Resource model & naming
• rdp-02: Standard methods
• rdp-03: Custom methods
• rdp-04: Field masks
• rdp-05: Long-running operations
• rdp-06: Batch operations
• rdp-07: Soft deletion & request validation
• Case studies: design framework
• Prep: design method cheatsheet
• Security 08: API keys, JWTs & hardening
• Reliability 01: API versioning