Soft deletion

As explained in API Design Patterns

Soft deletion is a deletion technique that marks a resource as deleted while retaining it until later physical removal or completion of a deletion process.

Soft deletion marks a resource as deleted without immediately removing its stored data. The resource disappears from ordinary views but can be restored or permanently removed later, providing protection against mistaken destructive requests. section 25.0 section 25.1

Implement soft deletion by making the deleted state explicit and adapting the resource methods around it:

• Store deletion status in a deleted Boolean field or a deleted value within an existing state enumeration. section 25.2
• Change DELETE to mark the resource as deleted rather than remove it, and make ordinary LIST requests exclude deleted resources by default. section 25.3 section 25.3.2
• Let GET return a known soft-deleted resource, while allowing LIST callers to request deleted resources explicitly, such as with includeDeleted. section 25.3.2
• Add undelete to restore a resource and expunge to remove it permanently; define errors for invalid repetition and decide how expiration is handled. section 25.3.3 section 25.3.9
• Preserve the existing referential-integrity rules instead of weakening deletion restrictions merely because the underlying data remains present. section 25.3.6

Chat-room API

A ChatRoom resource can expose deleted and expireTime fields. DELETE /chatRooms/{id} marks the room deleted and returns it; GET /chatRooms/{id} can still retrieve it; ordinary LIST omits it unless includeDeleted is true. POST /chatRooms/{id}:undelete restores it, while POST /chatRooms/{id}:expunge permanently removes it. section 25.3.2 section 25.3.9

Treat soft deletion as a trade-off: it reduces damage from mistakes but delays permanent removal and consumes storage. Regulated data may require immediate deletion or may prohibit expunging, so retention, privacy, and security requirements determine whether the pattern fits. Adding it to an existing API can also change method semantics enough to require a major version. section 25.3.8 section 25.4

Figure 25.1 Life cycle of a resource being soft deleted and expunged

Use the resource life cycle to distinguish active, soft-deleted, restored, expired, and expunged states. section 25.2

How API Design Patterns covers it

How deep it goes

Defines storage markers, modifies GET, LIST, and DELETE, adds undelete and expunge, and addresses integrity, repetition, expiration, and versioning.

Examples

Uses ChatRoom endpoints, includeDeleted listing, undelete, expunge, deleted, and expireTime to demonstrate the resource lifecycle.

What it assumes

Assumes standard resource methods and API versioning, while teaching deletion-state representation and method changes explicitly.

What you can do after

Operate a soft-deleting resource API with explicit listing, restoration, permanent-removal, expiration, and referential-integrity rules.

How it connects

Connects soft deletion with hard deletion, referential integrity, identifier permanence, resource identification, and API versioning.

liveBookmanning.com

Read API Design Patterns on liveBook Get the book at manning.com

Also explained in

• 

  liveBookmanning.com
  ASP.NET Core in Action, 3eSoft delete is a deletion technique that marks a record as deleted so it is excluded from application exposure while remaining stored.

Compare how 2 books explain soft deletion →

Related concepts

• hard deletealternative to · A hard delete permanently removes data or a resource from its physical storage rather than merely marking it as deleted.
• HTTP methodimplemented by · An HTTP method is a standardized operation token in an HTTP request that specifies the intended action on a resource.
• list methodused by · A list method is an API operation that retrieves the resources belonging to a specified collection.
• booleanuses · A Boolean is a logical type or value representing truth or falsity, conventionally with two states: true and false.
• undeleteuses · Undelete is the operation of restoring a resource that was marked as deleted without being physically removed.
• tradeoffcontrasts with · A tradeoff is a situation in which improving one objective or property requires accepting a cost, limitation, or reduction in another.

This explainer was generated by Manning's knowledge graph from the text of API Design Patterns. The section links point to the parts of the book it draws on.