RFC 2616 defines names for the various HTTP response codes. Unfortunately, the names Piston uses for the rc.* helpers don't match. I found this really confusing, and it led to a number of places where I was using HTTP codes incorrectly.
These helpers should be renamed to match the RFC (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). These differences are important. Here's the differences between Piston and RFC; I'll explain why each is a problem below:
Code Piston's name RFC Note
200 OK OK
201 CREATED Created
204 DELETED No Content  400 BAD_REQUEST Bad Request
401 FORBIDDEN Unauthorized  404 NOT_FOUND Not Found
409 DUPLICATE_ENTRY Conflict  410 NOT_HERE Gone  501 NOT_IMPLEMENTED Not Implemented 503 THROTTLED Service Unavailable  }}}
Okay, so why are these names misleading?
204 is indeed the correct response to a
DELETE. However, it's also used in a number of other contexts -- it's a valid response to a
PUT that updates a resource, for example. The RFC says that 204 is used whenever "the server has fulfilled the request but does not need to return an entity-body," which is a lot more often than after a
This is actually a really big problem. HTTP has two different types of "authentication failure" codes, and this naming confuses the two.
401 means "unauthorized"; it indicates that the given request requires authorization. The response can include a
WWW-Authenticate header indicating how authentication ought to be performed. The RFC notes that "the client MAY repeat the request with a suitable Authorization header field".
403, on the other hand, is "forbidden"; it indicates that "authorization will not help and the request SHOULD NOT be repeated." You might return a 403 if the password given for the user doesn't match, for example.
Naming 401 "Forbidden" is confusing, and wrong. It was that discovery that prompted me to write this bug.
409 conflict usually does indicate a duplicate entry, but it's also often used in transactional contexts to indicate that someone else's transaction conflicted with yours and prevented commit. The naming obscures that (and other) uses.
"Not here" sounds a lot like "Not found" to me. "Gone", on the other hand, indicates that the resource once was there, but is no longer. There's an important difference which (again) the name obscures.
503 is useful for a lot more than throttling.
Again, please rename these codes to be consistent with the RFC.