Designing Delete APIs

When a customer deletes a reading list, the expected result extends beyond removing a record. Its saved link should stop working, but the books it referenced should remain in the catalog, and another list containing those books should remain intact. If the response disappears in transit, repeating the request should not cause additional damage.

A delete API defines the boundary of removal, the moment that removal becomes effective, and what callers can observe afterward.

This chapter uses a fictional bookstore to explain successful deletion, related resources, permissions, retries, version conditions, and background work. Examples use HTTPS at https://api.bookstore.example.