What to advertise in Allow: header for overloaded POST

Question

Overloading POST is a common practice with REST APIs, especially when using HTML as a media type.

But I'm wondering what is the proper way to advertise overloaded POST in the Allow: header.

With a typical resource that can be, say, read and updated, one might expect:

Allow: GET, HEAD, PUT

But when I have to overload POST for PUT, should the Allow: header now mention that POST is accepted? Should it stop mentioning PUT if I expect to only receive overloaded POST requests?

Answer 1

I'd always look at these sorts of questions behaviorally, in terms of which clients will care about that aspect of the response, and what would it affect in those clients.

So, specifically, which clients care about and use the Accept header, and what would the implications be for those clients?

Firstly there's web browsers. My initial thought was that if you're using CORS then the value of the Accept header might be relevant to the web browser, and might need to include POST. However that's actually Access-Control-Allow-Methods. So as far as I'm aware the Allow header doesn't actually have any behavioral implication for browser clients.

Then there are programmatic clients. In those cases the non-overloaded methods are mostly likely the ones you want to list. (Eg. Perhaps you'll have documentation generating client that inspects and displays the allowable methods. Also it makes more sense from the user's point of view.)

Finally, there's users who are inspecting your API responses visually. In that case I'd probably prefer the overloaded set of methods again, as being more informational.

---

In short - I'd probably go with just listing the overloaded set of methods that are allowed, and not including POST. The browser is generally the only client that'll make overloaded requests, and I'm not aware that it uses or inspects the Accept header in any way.