...
- 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
Tests
- Can retrieve items
- With a logically deleted item, the includeDeleted flag shows/hides these logically deleted items
- Physically deleted item does not appear regardless of the includeDeleted flag (this is a good integration test)
GET /apples/id
- always return this item regardless of deletion status so references do not break
- Note: if developers try and delete things to verify they are not referencing older models in their apps, this aspect of our API could be misleading. Their apps will continue to work. Just something to be aware of.
Tests
- Can retrieve item regardless of whether or not it is marked deleted
POST /apples
- should not be able to create an apple in a deleted state (deleted always = false)
...
- should be able change the deleted flag if you can update the object
Tests
- If item is deleted and update is undeleted, this is allowed and resulting item is not deleted
- If item is not deleted and update is deleted, this is allowed and resulting item is deleted (no need to prevent this)
- If item is deleted and update is deleted, then throw an EntityNotFoundException
- If item is not deleted and update is not deleted, this is allowed and the resulting item is not deleted
DELETE /apples/id or DELETE /apples?id=x
- sets deleted = false and that's it. This is an option for both developers and administrators.
Tests
- If item is already logically deleted, throw 404
- If item is not marked deleted, mark it as deleted
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)
Tests
- If item is not in database, return 404
Physically deleting an entity that's marked as deleted should work, rather than returning a 404. Updating a logically deleted entity to undelete it should work. Updating a logically deleted entity, when you're not also undeleting it, should return 404. In other cases, we continue to return 404 when updating or deleting something that doesn't exist in the database.
...