json-api delete example

[nickdu]

I didn't see a json-api discussion group so I figured this group might be appropriate.  If someone knows of a better group please pass that along.  Looking at the json-api spec at http://jsonapi.org/format/ I see the following example:

DELETE /articles/1/links/comments
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": { "type": "comments", "ids": ["12", "13"] }
}

Note: RFC 7231 specifies that a DELETE request may include a body, but that a server may reject the request. This spec defines the semantics of a server, and we are defining its semantics for JSON API.

Which looks a bit odd to me as I'm used to seeing delete operate on the URL (resource) you're deleting.  Not sure if this is some sort of performance thing so that multiple resources can be deleted with one request.  Does DELETE impact any HTTP caching?  I would assume it at least invalidates the resource.  If so, in this case wouldn't it be invalidating the wrong resource?

Thanks,
Nick

[Steve Klabnik]

We don't have a specific JSON API discussion group, so this is a good
place to ask.

[Onezino Gabriel Moreira]

I like how the json-api does things. And  personally I find it very reable and nice.

As a repository we should be able to remove a set of content, avoiding redo several time a request.

[erewhon]

According to the spec (section 9.7 of 2616) a cache should treat a deleted resource as stale.  Deleting comments from a collection probably should invalidate the cached collection, though.

The spec also indicates that your DELETE operation should eventually remove the resource or make it "inaccessible" and that the DELETE operation should be idempotent.  In your case the collection is still available, but this is to me, a pragmatic and acceptable interpretation of the spec.

The approach you've highlighted isn't bad, but it might be worth asking whether or not a bulk DELETE is really required.  If you have clients that occasionally need to delete comments, is the volume high enough to warrant a special use case for DELETE?  The alternatives to your approach are probably all at least as complex (if not more so) and may only give you semantic benefits rather than technical ones.

Personally, I don't think there's a big problem with it.

[nickdu]

How would a HTTP cache sitting in between know what is being deleted?

Thanks,
Nick

[erewhon]

It wouldn't know about the IDs, just the resource specified by the URL.  If caches handle this at all, it would probably just be an invalidation of the /.../comments collection.

[nickdu]

And do you expect transactional semantics?  If it was able to delete one of the comments but not the other, what do you expect the server state to be?  What should the return value be?

Thanks,
Nick

[erewhon]

Good questions, I think these are application-level semantics.  I don't know what the best answer would be in your case, but I suppose you could reply with 204 No Content (everything succeeded) or 200 OK with a response body that indicates what succeeded and what did not.  Some may take issue with a 200 OK in this scenario, but I see it as a pragmatic compromise in order to allow for batch operations against your server.

The alternative would be to explore singular DELETE operations with the use of pipelining, or perhaps creating a generic batch interface, of which I am aware of two potential strategies: custom batch contracts or multipart HTTP.  Examples:

https://developers.facebook.com/docs/graph-api/making-multiple-requests
https://cloud.google.com/storage/docs/json_api/v1beta1/how-tos/batch