Define error code for unaccepted posts

[gerwitz]

3.8 Error Response does not define a response for valid requests that cannot be handled by the server.

I am using and recommend:

HTTP 501: "error":"unaccepted_content" - The request is valid but this server does not implement handling this content.

(Also, the 400 example is lacking a sentence-terminating period.)

[aaronpk]

I'm really on the fence about using HTTP 5xx responses to indicate any sort of application-level information. Currently any time a client gets an HTTP 5xx error, it can assume something went wrong with the transport of the request, such as a gateway timeout.

In REST APIs, HTTP 501 indicates that the HTTP method itself is unsupported, which in this case is a POST request. Micropub is not a REST API though, so I would be worried that a 501 could inadvertently indicate to a client that a POST request is not supported.

Can you find examples of other non-REST APIs that use HTTP 501 for this feature? I wouldn't want to recommend 501 unless there are existing examples of other non-REST or RPC APIs using it.

[gerwitz]

I have no strong opinion here, 501 arose from discussion on the IWC Slack.

My API experience falls into REST and deep-stack buckets. Micropub is lighter weight than any non-REST protocol I've used or implemented over HTTP, so it "feels" right for it to act RESTy.

To defend my recommendation, if it's not appropriate to use HTTP codes, why does the spec call for the use of 4xx codes, rather than replying with a 2xx that includes error details?

[aaronpk]

The 4xx codes were inherited from OAuth 2.0, which defines a few 4xx codes when using access tokens, https://tools.ietf.org/html/rfc6750#section-3.1 and using 400 as a catch-all for any client errors.

[gerwitz]

That makes sense, but now that the precedent has been set that HTTP status codes reflect API responses, shouldn't we continue with that for consistency?

[voxpelli]

This seems somewhat related to #61, which was moved to: https://indieweb.org/Micropub-brainstorming#Provide_end-user_error_messages

To me this would be the best way to add the suggested error:

HTTP 400: "error":"unaccepted_content" - The request is valid but this server does not implement handling this content.

But the error name should probably be unknown_content as unaccepted_content can be data that the server knows how to handle, but which doesn't comply with certain limitations that the server imposes (the latter error is somewhat what I suggested in #61)

[gerwitz]

+1 on unknown_content based on #61

I see on #43 that I'm not likely to convince the crowd on 5xx, but that might not stop me from implementing. 🤠

[gerwitz]

For the record: on the Sitewriter endpoint I am returning 422 (with "unaccepted_content") based on this discussion: https://stackoverflow.com/a/4786067/5610