DELETE in a REST API without an entity ID best practice - rest

Question

I have a timespan I want to delete in a REST API.
It doesn't have an id so calling HTTP DELETE on "/timespan/" is not really possible. The implementation would be possible, but I would rather not put in the extra effort (requires some database modifications) unless there is a good reason to add it.
I considered calling DELETE on "/timespan/" with "start" and "end" inside the request but to my understanding this clashes with the way REST works.
Is it legit to call DELETE on "/timespan//" or maybe a concatenation such as "/timespan/+" or should I implement IDs after all?

Answer 1

You are correct. DELETE doesn't take a body.
RFC 7231:
A payload within a DELETE request message has no defined semantics;
sending a payload body on a DELETE request might cause some existing
implementations to reject the request.
I've seen what you want done as
DELETE /sites/{siteId}/maintenance
but that's really not optimal. If maintenance is a resource, it needs some way of being uniquely identified. If it's a property of a resource, then you delete it via PUT or PATCH on that resource.

Answer 2

Assuming your resource is a maintenance performed on a site. The API could have:
DELETE /sites/{site-id}/maintenances/{maintenance-id} to delete one maintenance. The typical delete.
DELETE /sites/{site-id}/maintenances to delete all maintenances of a given site. Not usual, and dangerous.
DELETE /site/{site-id}/maintenances?start={start-date}&end={end-date} to delete all maintenances in a timespan. The answer to your question.
Rationale: the timespan is not part of the resource, it's a filtering attribute on the collection of resources. Therefore, it should not be part of the URI (Uniform Resource Identifier). We should use query string parameters for filtering.
Another option:
POST /site/{site-id}/clean-up to delete all maintenances of a given site that are within the timespan specified in the request body. Also an answer to your question.
Rationale: some advocate that a REST API can offer more "coarse-grained" operations that closely resemble the business capability in complement to (or in the place of) more CRUD-like APIs. Here's a reference. In the particular case, the POST operation executes a "clean-up business process". The start and end dates go in the request body. The operation should return 200 (not 201) for success.

Answer 3

Instead of designing a low-level CRUD-like REST API and let the callers know details about your domain, you could let the client POST their intent and let the server decide what to delete. Seems like the right approach if you ant to prevent users from accidentally (maliciously?) deleting resources. More in Fine grained CRUD resources versus Coarse Grained resources at http://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling

Answer 4

If you are following the RESTful principle closely, you would need to retrieve a list of resources (partial as proposed by #moonwave99) and invoke DELETE on every resource whose timestamp is older than a certain threshold. This conveis the semantics of delete while being completely idempotent. You, however, need a resource identifier therefore (which you should have obtained via the previous retrieve).
The next choice would be to set off a PUT request where you send each and every entry that should be available after the request within that request. In practice this is however a no-go as to much data would need to be transfered.
Last but not least, you would have the possibility to delete resources via PATCH where you pass the necessary instructions to the server it needs to transform the resource(s) from state_before to state_after. In case of json-patch you have the remove operation at hand. However, the spec does not provide any possibility to remove a state if a certain condition was met - a combination of test+delete would be handy in that case. The quintesence is though, that not the server is responsible for filtering out certain data but the client which has to send each necessary step to the server. Therefore, a client has to retrieve the current state of a resource collection like /api/sampleResources which could be an array of JSON objects and do the decission locally:
HTTP/1.1 200 OK
...
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
...
[
{
...
"timestamp": "2015-07-17T19:40:00",
...
},
{
...
"timestamp": "2014-10-05T10:00:00",
...
},
{
...
"timestamp": "2015-07-16T15:00:00",
...
},
{
...
"timestamp": "2014-12-31T00:00:00",
...
}
]
If all entries from the last year should be deleted, a JSON-PATCH request would need to look like this:
PATCH /api/sampleResources
...
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
...
[
{ "op": "remove", "path": "/1" },
{ "op": "remove", "path": "/3" }
]
The path is specified in JSON Pointer notation and is 0 based, therefore the sample above removes the second and fourth entry of the list, which are the entries of 2014.
As the resource can be modified between the lookup and the patch generation, it is highly recommended to use ETag features to gurantee that the patch is executed on the right state. If the ETags do not match, the request fails with a precondition failure.
Note however, that PATCH is not idempotent! So sending the same request twice may delete more entries as intended. This is not the case with PUT, as the state after the request is exactly the state you told the resource to have. Therefore, sending the same request twice does not change anything state-wise. In comparison to a bunch of DELETE requests, PATCH is atomic - either all or none of the operations are executed, while the DELETE requests are all independent.
I agree strongly, that there is a need for conditional and partial PUT and DELETE operations to adhere to the business needs. For simplicity reasons I would really recommend to use partial GET and DELETE operations instead of PUT or PATCH.