[Catalyst] Re: RESTful response codes.

[Aristotle Pagaltzis]

* Bill Moseley <moseley at hank.org> [2012-02-24 03:00]:
> I was going to disagree with you, but I think we are talking about two
> differnt things.
>
> For a 400 response I completely agree with you. In that case I do
> return a very detailed and standard-formatted response that explains
> why the client request could not be processed.

Right. A 4xx response says you couldn’t give the client the thing it
asked for, which means the response body bears no relation to the
content of the thing anyway and could be anything you deem useful in
that scenario. A machine-readable structured error message is the
obvious option.

> This consumer of he API is arguing that the 2xx HTTP response are not
> enough of a "status" -- that *every* request needs a status (and that
> should not mix HTTP "transport" codes with business logic). But,
> I cannot think of an example where this would be the case.

It is the wrong way to think of HTTP. HTTP is an application protocol,
not a transport protocol. Rather than a network layer for carrying the
arbitrary semantics specific to your application, it is a standardised
vocabulary for expressing application semantics in a general way.

That means sometimes one has to constrain an application design in order
to fit it into HTTP. But that is not an arbitrary capricious lack of
freedom, rather HTTP is derived from a set of principles designed to
guarantee a particular set of characteristics. Those are what one gets
those in exchange for abiding by HTTP’s restrictions.

This API consumer’s request is mistaken in two ways:

1. They are essentially arguing that your application needs arbitrary
   application-specific semantics beyond the vocabulary. That is a…
   rather contestable premise. Far from everything fits into HTTP but
   few who claim special snowflake status have grounds for it.

2. The mechanism they suggest is broken. In a 200 response the body is
   supposed to represent the state of the *resource*, expressed in some
   concrete format. What they are asking you to put in the response body
   is information about the *request*. That does not belong there. This
   is another indicator that they are thinking about HTTP as a transport
   protocol.

In short, I suggest you don’t listen.

> So you do GET /user/1234 and it returns a 200 with a status saying
> { status => "here's the user you asked for, but I was not able to look
> up their LDAP id because the server was down.  Hope you don't mind the
> omission." }. That's a scary road to head down, no?

That’s even worse than the suggestion above, it’s plain broken.

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>