Skip to content

Instantly share code, notes, and snippets.

@dehora
Last active August 23, 2016 12:39
Show Gist options
  • Save dehora/409a14c52eece610c501 to your computer and use it in GitHub Desktop.
Save dehora/409a14c52eece610c501 to your computer and use it in GitHub Desktop.
Batch 207 Arcana

WebDav put the 207 multi-status response code into the 2xx class regardless of per item errors, because for its usecase the top level response class don't matter. Also none of the error classes were a clear winner over 2xx. Even a batch with all failed items gets mapped to a success level code - but what really matters in Dav are the per item codes.

   Although '207' is used as the overall response status code, the
   recipient needs to consult the contents of the multistatus response
   body for further information about the success or failure of the
   method execution.  The response MAY be used in success, partial
   success and also in failure situations.

The reason that's important to mention is because HTTP response codes are broken into classes to allow clients to function even when they don't understand a specific response (a 2xx always means some kind of success, a 5xx always means some kind of server error, etc).

In general then sending back 2xx for a partial failure looks like a design flaw that breaks http clients working with response classes. But WebDav designed around that problem - a client can't get a 207 unless it knows how to ask for one because it's only used in WebDav for certain extension methods or when the client supplies particular headers (eg for a collection DELETE). So generic client handling on 2xx/3xx/4xx still works as expected in WebDav. Even then WebDav allows a 4xx to be returned instead for total failures in the delete case -

   The server MAY return a 4xx status response, rather than a 207, if
   the request failed completely.

The catch, if you can call it that, with using 207 in general for modern API batch calls (typically using POST) is that you can't simply switch on the main class anymore because the client isn't qualifying its request such that you might treat a partial (or total) batch failure as everything's fine via a centralized handler. You have to code to look for it specifically. Yaron Goland identified this as a hazard as far back as 1999.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment