REST and PHP multifile upload: what http status should return if some (but not all) files fail to upload?

Question

So, I'm building out a PHP-based CMS application that is grounded in RESTful principles (though it certainly veers from them), and I've run into a bit of a dilemma:

What is the proper HTTP status to return when POSTing a form that uploads multiple files and some uploads succeed while others fail due to filename conflict? "409 Conflict" seems to make sense for each individual failed upload, but for the overall POST, which comprises an array of successful and failed uploads, it doesn't seem so clear cut.

My confusion is predicated on my perception that a multifile upload constitutes a single POST request, not one POST request for each file being uploaded. Is that correct?

Answer 1

You are correct. If you are POSTing a collection, the collection itself is the resource. So if the collection resource was created, you'd return a 201. If it was accepted but not fully processed, you'd return a 202.

If you are implementing parts of the resource on the server with multiple files and there are already existing files that get in the way of a successful POST, you'd return a 409 and not create the collection resource and fail the whole operation. From the REST perspective, it's an atomic operation.

If, on the other hand, you were to support a PUT operation for this resource, you have to support idempotency. So one behavior might be to simply replace any files that were existing as part of the resource with what's being included with the PUT body. You could consider doing this as well for a POST, but that will only work if the existing file names belong to at most one collection resource. Otherwise you might end up trashing someone else's collection.