Resource Design Patterns · Lesson 07

Soft deletion & request validation

Deleting data is easy; recovering it after an accidental delete is painful. Soft deletion separates the logical act of deletion from the physical act of destruction — giving users a recycle bin and giving you a safety net. Pair it with validate_only, and clients can rehearse any mutation before they commit it.

The recycle-bin model: why real systems don't hard-delete by default

Imagine a developer calls DELETE /v1/projects/proj_42/tasks/task_99 on a Friday afternoon. The task disappears. Two hours later the team realizes it was the only record of a regulatory requirement. Hard deletion has no undo — the data is gone, and the only recovery path is a database restore that costs hours of downtime and risks losing all other work done since the last backup.

Soft deletion solves this by making DELETE mean "move to the recycle bin," not "destroy immediately." The row stays in the database; a delete_time timestamp is stamped on it; normal queries filter it out so it is invisible to day-to-day operations. At any point within a retention window — 30 days is a common default — a user can restore the resource. After the window expires (or immediately if a privileged caller uses :expunge), the data is permanently destroyed.

Google Cloud APIs codify this in AIP-164. The pattern appears in Google Drive, Gmail (the Trash folder), and many internal Google services. Most SaaS products that handle business data implement a variant of it.

The soft-delete lifecycle

Modeling soft deletion on the Tasks API

A soft-deleted task carries two new fields on the resource body:

• delete_time — an RFC 3339 timestamp set when the task is soft-deleted. Null (omitted) on active tasks.
• expire_time — an RFC 3339 timestamp after which the server will automatically expunge the task. Typically delete_time + 30 days. Optional — some APIs omit it and rely on a server-side policy instead.

The standard GET, LIST, UPDATE, and PATCH methods all implicitly filter out deleted resources. You must pass show_deleted=true to surface them in LIST. GET on a deleted resource returns it (the caller knows the ID), but PATCH and UPDATE on a deleted resource return 400 FAILED_PRECONDITION — you cannot edit a deleted resource, only undelete or expunge it.

Worked example: the full soft-delete lifecycle on Tasks

Step 1 — Soft-delete a task

# Standard DELETE — no body required
DELETE /v1/projects/proj_42/tasks/task_99
Authorization: Bearer <token>

----- response 200 OK -----
{
  "name":        "projects/proj_42/tasks/task_99",
  "title":       "Finalize compliance checklist",
  "status":      "OPEN",
  "delete_time": "2026-06-20T14:00:00Z",
  "expire_time": "2026-07-20T14:00:00Z"
}

The server returns the updated resource body — not 204 No Content — so the caller can confirm the delete_time and expire_time. (Some implementations return 204; returning the resource is friendlier for clients.)

Step 2 — List with show_deleted to confirm it is in the bin

GET /v1/projects/proj_42/tasks?show_deleted=true
Authorization: Bearer <token>

----- response 200 OK -----
{
  "tasks": [
    {
      "name":        "projects/proj_42/tasks/task_01",
      "title":       "Update onboarding docs",
      "status":      "OPEN"
    },
    {
      "name":        "projects/proj_42/tasks/task_99",
      "title":       "Finalize compliance checklist",
      "status":      "OPEN",
      "delete_time": "2026-06-20T14:00:00Z",
      "expire_time": "2026-07-20T14:00:00Z"
    }
  ],
  "next_page_token": ""
}

Step 3 — Restore with :undelete

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

{}

----- response 200 OK -----
{
  "name":        "projects/proj_42/tasks/task_99",
  "title":       "Finalize compliance checklist",
  "status":      "OPEN",
  "delete_time": null,
  "expire_time": null
}

Both delete_time and expire_time are cleared. The task is fully active again, with the same name and all original fields preserved.

Step 4 — Hard-delete with :expunge

# Requires elevated permission — irreversible
POST /v1/projects/proj_42/tasks/task_99:expunge
Authorization: Bearer <admin-token>
Content-Type: application/json

{}

----- response 200 OK -----
{}

# Subsequent GET returns 404 — the row is gone
GET /v1/projects/proj_42/tasks/task_99
→ 404 NOT_FOUND

:expunge is a custom method (per rdp-03) that permanently destroys the row. Require a separate permission scope — e.g. tasks.expunge — so the ability to soft-delete does not imply the ability to hard-delete.

Request validation: the validate_only flag

Sometimes a client needs to know whether a request would succeed — before committing side effects. A new task form might want to validate the assignee and due date in real time without creating a draft. A bulk import tool might want to pre-check 500 rows for errors before writing any of them.

The validate_only flag (see AIP-163) solves this. When a request includes "validate_only": true in the body (or as a query parameter), the server runs all validation — schema checks, business rules, permission checks — and then stops. It neither creates nor modifies anything. If validation passes, it returns 200 OK with an empty body (or the resource as it would appear if the request were committed). If validation fails, it returns the same errors it would return for a real request.

Think of it like a spell-checker that runs on your draft without sending the email. You see exactly the errors you would get, at the exact time you would get them, with zero risk of accidental mutation.

Worked example: validate_only on CreateTask

# Dry-run: will this task be accepted?
POST /v1/projects/proj_42/tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "validate_only": true,
  "task": {
    "title":    "Prepare quarterly report",
    "notes":    "Include revenue breakdown per region",
    "due_time": "2026-07-01T17:00:00Z",
    "assignee": "users/alice",
    "labels":   ["finance", "q2"]
  }
}

----- response 200 OK (nothing created) -----
{}

# Now try with a bad assignee
{
  "validate_only": true,
  "task": {
    "title":    "Prepare quarterly report",
    "assignee": "users/doesnt-exist"
  }
}

----- response 400 INVALID_ARGUMENT -----
{
  "error": {
    "code":    400,
    "status": "INVALID_ARGUMENT",
    "message": "Field 'assignee': user 'users/doesnt-exist' not found."
  }
}

Under the hood: how it actually works

Soft delete mechanics in the database

The simplest implementation adds a nullable deleted_at column (matching delete_time) and a nullable expires_at column to the resource table. A server-side predicate WHERE deleted_at IS NULL is appended to every standard SELECT except those with show_deleted=true. Almost all major ORM frameworks support this via a global scope — e.g. Rails' default_scope { where(deleted_at: nil) }.

The hard part is not the delete — it is the unique-constraint problem. If you soft-delete a task named "Finalize Q2 report" and then create a new one with the same title in the same project, you now have two rows with the same business identity. Design your uniqueness constraints to include deleted_at in the index (partial index WHERE deleted_at IS NULL), or use a separate "tombstone" table to track deleted names, to prevent ghost-name collisions.

Automatic expiry: a background sweeper

A separate background job (a cron or a message queue consumer) runs periodically — say, every hour — and executes a query like:

This decouples the expiry logic from the request path. The :expunge custom method is the user-triggered version of the same operation, run immediately and on demand.

validate_only implementation pattern

The cleanest implementation extracts all validation logic into a validator function that returns errors without touching the database. The create handler calls: (1) validate(request); (2) if validate_only == true, return 200 {}; (3) otherwise persist(request).

The key guarantee is that validation in validateCreateTask is identical whether or not validate_only is set. Any drift between the dry-run and real paths defeats the purpose of the flag — the client would get a clean dry-run and then a real-run error. This is a common bug in naive implementations.

Related pattern: resource revisions

Soft deletion is about lifecycle. A related but distinct pattern is resource revisions (change history): keeping a numbered snapshot of every version of a resource so you can view or restore any past state — not just "deleted vs active." Revisions are covered in AIP-162. They pair well with soft deletion: an accidental update to a task can be reversed by restoring a revision, while an accidental delete is reversed by :undelete. Together they give users a complete undo history.

Sources & further reading

• Google AIP-164 — Soft delete
• Google AIP-163 — Request validation (validate_only)
• Google AIP-162 — Resource revisions
• Resource Design Patterns — Lesson 02: Standard methods
• Reliability — Lesson 02: Idempotency