We'd like to have a consistent and safe way for study designers (almost always the implementers, so people with the DEVELOPER role) to delete and remove things as they set up a study. Often out deletes actually remove things from the database, and so those calls are only accessible to administrators for test clean-up.
Here's how we'll support both through our rest API:
class Apple
boolean deleted - this flag should be part of the public API of the object.
GET /apples?includeDeleted=boolean
- by default, should not include deleted apples
- because deleted apples may be referenced elsewhere, UIs may still need them for labels, etc., so include a flag to return deleted apples, too
GET /apples/id
- always return this item regardless of deletion status so references do not break
POST /apples
- should not be able to create an apple in a deleted state (deleted always = false)
POST /apples/id
- should be able change the deleted flag if you can update the object
DELETE /apples/id or DELETE /apples?id=x
- sets deleted = false and that's it. This is an option for both developers and administrators
DELETE /applies/id?physical=true or DELETE /apples?id=x&physical=true
- physically removes item from database if and only if the caller is an administrator (otherwise falls back to a logical delete)