Resource Design Patterns · Lesson 03

Custom methods — when CRUD isn't enough

Most resources live happily inside create, read, update, and delete. But some operations — completing a task, moving it between projects, archiving a whole workspace — carry meaning and side effects that a plain data write can't express. Custom methods give you a principled, spec-backed way to reach beyond CRUD without losing REST's identity.

Why CRUD breaks down

Imagine you run a postal sorting facility. The standard operations are obvious: add a parcel (create), look it up (read), update the delivery address (update), remove a cancelled shipment (delete). But what happens when a parcel ships? Shipping isn't just writing status = "shipped" — it triggers downstream effects: the carrier is notified, the tracking number is generated, the warehouse inventory is decremented, and the customer gets an email. The operation has a name — "ship this parcel" — and a contract — it either succeeds fully or rolls back. Squashing that into a PATCH call obscures intent, scatters side-effect logic, and gives your callers no signal that something significant just happened.

This is the gap that custom methods fill. They are purpose-named operations on a specific resource, distinct from its CRUD lifecycle, with their own request payload and response contract.

The colon-suffix convention

Google's API Improvement Proposals (AIPs) codify this pattern as AIP-136. The rule is simple: append a colon and a verb to the resource URL, and always use POST.

# Custom method on a single resource
POST /v1/projects/{project}/tasks/{task}:complete
POST /v1/projects/{project}/tasks/{task}:move
POST /v1/projects/{project}/tasks/{task}:assign

# Custom method on a collection or parent resource
POST /v1/projects/{project}:archive
POST /v1/projects/{project}:restore
POST /v1/documents/{document}:publish

Why always POST?

You might expect a "get suggestions" custom method to use GET, and an argument could be made. But AIP-136 mandates POST for all custom methods for three reasons:

1. Side effects. Custom methods almost always mutate state or trigger external actions. POST is the correct semantic for non-safe, non-idempotent-by-default operations. Using GET for a side-effectful call violates the HTTP safety contract and risks being silently re-fetched by proxies and prefetch heuristics.
2. Request body. Many custom methods need parameters — a destination project ID for :move, or a reason for :archive. GET has no defined body semantics. POST gives you a structured JSON body without resorting to query-string encoding of complex data.
3. Uniformity. A single rule ("custom methods are always POST") is simpler to implement, document, and lint than per-method exceptions. Router logic and auth middleware only need one pattern to match.

Why a colon, not a slash?

A slash would make :complete look like a child resource: /tasks/task_77/complete — something you could GET, PUT, DELETE. The colon makes the operation/resource distinction syntactically unambiguous. The resource is /tasks/task_77. The colon-verb is an action on it, not a sub-resource of it. URL parsing is unambiguous: split on the last colon in the final path segment and you have the resource name on the left and the method name on the right.

Decision tree: custom method vs PATCH vs sub-resource

Before reaching for a custom method, run through this decision order:

The sharpest test: could the caller achieve this by PATCHing a field, and would that be safe? If writing {"status": "completed"} via PATCH would skip the notification, leave completed_time unpopulated, or allow invalid transitions (e.g. completing an already-deleted task), then you need a custom method. PATCH is a data channel; custom methods are a behaviour channel.

SVG decision flowchart

Worked example: :complete

Completing a task in the Tasks API is the classic case for a custom method. It is not a pure field write — it must stamp completed_time atomically, enforce the state machine (you cannot complete an already-deleted task), and may trigger downstream notifications. Here is the full wire exchange:

# Request — empty body is valid; :complete needs no parameters
POST /v1/projects/proj_42/tasks/task_77:complete HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json

{}

# Response — full resource returned, status and completed_time updated
HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "projects/proj_42/tasks/task_77",
  "title": "Finalise API spec",
  "status": "completed",
  "completed": true,
  "completed_time": "2025-06-18T14:32:00Z",
  "assignee": "users/ada",
  "due_time": "2025-06-20T17:00:00Z",
  "create_time": "2025-06-01T09:00:00Z",
  "update_time": "2025-06-18T14:32:00Z"
}

Several design choices are worth calling out:

• Empty body is allowed. :complete needs no caller-supplied arguments. Sending {} is idiomatic; some implementations also accept a missing body. Document which you support.
• 200, not 201. You are not creating a new resource — you are mutating an existing one. 200 with the updated resource is the correct status.
• Full resource in the response. AIP-136 recommends returning the full resource so clients can update their local state without a follow-up GET. Never return just {"ok": true}.
• Idempotency. Calling :complete on an already-completed task should be safe — return 200 with the existing resource unchanged, rather than 409. The task is in the desired final state; returning an error would force callers to check before every call.

Worked example: :move

Moving a task between projects is a cross-resource operation. It cannot be expressed as a PATCH (the resource's canonical URL changes), and it does not create a child record. It is exactly the kind of bounded domain action that custom methods exist for.

# Request — destination_project tells the server where to move the task
POST /v1/projects/proj_42/tasks/task_77:move HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "destination_project": "projects/proj_99"
}

# Response — task now lives at its new canonical name in proj_99
HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "projects/proj_99/tasks/task_77",
  "title": "Finalise API spec",
  "status": "open",
  "completed": false,
  "assignee": "users/ada",
  "due_time": "2025-06-20T17:00:00Z",
  "create_time": "2025-06-01T09:00:00Z",
  "update_time": "2025-06-18T14:33:00Z"
}

The name field in the response reflects the new canonical path — projects/proj_99/tasks/task_77 — not the URL the request was sent to. Any client that cached the old URL needs to update its reference. Note that status is reset to "open": the task enters the destination project's default state. This business rule belongs here, not in a PATCH handler, because it is part of the semantics of "moving" a task.

Under the hood: how it actually works

Understanding what happens in the router and handler helps you design the right contract and debug issues when they arise.

Router parsing

The colon-suffix is parsed as part of the final path segment. A typical routing table entry looks like:

// Express-style pseudo-code
// The router registers the full literal :complete suffix as a method name
app.post('/v1/projects/:project/tasks/:task\\:complete', handlers.completeTask);
app.post('/v1/projects/:project/tasks/:task\\:move',     handlers.moveTask);

// Framework-agnostic: split on the last colon in the final segment
function parseCustomMethod(path) {
  const lastSegment = path.split('/').pop();          // "task_77:complete"
  const colonIdx    = lastSegment.lastIndexOf(':');
  if (colonIdx === -1) return { resource: lastSegment, method: null };
  return {
    resource: lastSegment.slice(0, colonIdx),  // "task_77"
    method:   lastSegment.slice(colonIdx + 1)  // "complete"
  };
}

State machine and idempotency

Custom methods that implement state transitions must be written with idempotency in mind. The contract for :complete is: after this call, the task is in the completed state. If it was already there, that is not an error — it is the desired outcome, already achieved. The handler should check the current state and short-circuit:

// Pseudocode handler for :complete
async function completeTask(req, res) {
  const task = await db.tasks.findById(req.params.task);
  if (!task)           throw notFound('Task not found');
  if (task.deleted)    throw failedPrecondition('Cannot complete a deleted task');

  // Idempotent: already completed → return current state, no-op
  if (task.status === 'completed') {
    return res.json(toResource(task));  // 200, no mutation
  }

  const now = new Date().toISOString();
  const updated = await db.tasks.update(task.id, {
    status:         'completed',
    completed:      true,
    completed_time: now,
    update_time:    now,
  });
  await notifications.send(updated);   // side effect: notify assignee
  res.json(toResource(updated));
}

Always return the full resource

The contract for custom methods that mutate a resource is to return the complete, updated resource representation — not a status flag, not a partial object. This lets clients treat the response as a fresh GET of the resource and update their cache or local state accordingly. It also makes the API easier to reason about in logs and debugging sessions.

Curl commands and routing walkthrough

How to debug & inspect it

Custom method issues usually fall into a handful of recognisable patterns. Here is how to quickly isolate each one.

Symptom → cause → fix

# Successful publish
POST /v1/workspaces/ws_1/documents/doc_88:publish
Content-Type: application/json

{}

# Response
HTTP/1.1 200 OK
{
  "name": "workspaces/ws_1/documents/doc_88",
  "status": "published",
  "published_time": "2025-06-18T15:00:00Z",
  "update_time": "2025-06-18T15:00:00Z"
}

Sources & further reading

• Google AIP-136 — Custom Methods — the normative specification for the colon-suffix convention, including naming guidance and standard custom method names
• Google API Design Guide — Custom Methods — practical guidance from Google on when and how to use custom methods in production APIs
• MDN — HTTP POST method — the canonical reference for POST semantics, including why it is the correct choice for side-effectful operations
• RFC 9110 § 9.3.3 — POST — the normative HTTP specification definition of POST and its relationship to resource mutations
• Google AIP-193 — Errors — error model used in this lesson for FAILED_PRECONDITION and other structured error codes