Skip to content


Subversion checkout URL

You can clone with
Download ZIP


Successful REST post is create returns 303 rather than 201 #424

lostcolony opened this Issue · 11 comments

4 participants


Using the REST handler, if post_is_create returns true, a successful POST returns a 303, See Other, rather than a 201 Created. Webmachine returns a 201. The appropriate item in the RFC for HTTP 1.1 is -

If a resource has been created on the origin server, the response
SHOULD be 201 (Created) and contain an entity which describes the
status of the request and refers to the new resource, and a Location
header (see section 14.30).

Responses to this method are not cacheable, unless the response
includes appropriate Cache-Control or Expires header fields. However,
the 303 (See Other) response can be used to direct the user agent to
retrieve a cacheable resource.

This seems a touch ambiguous, but it seems like if it's a post create, it should return a 201. From Webmachine's diagram this is decision tree nodes N11 and P11


I went in the Webmachine source to find answers. Before, I interpreted N11 as being "Do we have a Location header?" and since we had, because we set it, I figured we had to 303. But it seems in Webmachine this step is actually a value configured in the webmachine request object, and the check for whether this is a new resource is done in P11 (incidentally we already know this is a new resource, so there's no need for a check). I think we do need both. But it should be a resource property.

   The response to the request can be found under a different URI and
   SHOULD be retrieved using a GET method on that resource. This method
   exists primarily to allow the output of a POST-activated script to
   redirect the user agent to a selected resource. The new URI is not a
   substitute reference for the originally requested resource. The 303
   response MUST NOT be cached, but the response to the second
   (redirected) request might be cacheable.

This is related to #396. @bfrog will probably be interested.

We want to have either:

  • A resource created with a 201 with a Location header
  • A resource created with a 303 with a Location header
  • A successful POST with no resource created
  • A failure

We could have the following return values:

  • {ok, Path}
  • {redirect, Path}
  • true
  • false



See the ticket I linked to. We're hoping to simplify the whole thing.


Yeah it'll definitely look better for the resource and perhaps not so clear on Cowboy's side, but a good comment should take care of it.


Is this still in the works? I like the idea of returning a 201 instead of the 303. I could make a patch if the desired functionality is for matching on these return values:

{ok, Path} -> 201
{redirect, Path} -> 303
true -> 200
false -> 422

Not sure if this is still an issue or if cowboy will only be supporting 303's for resources that have been created, but thought I would check in on this as everyone at my work is curious about the 303's.




true when the resource is new, with a location header set: 201
true without either: 200, 204 or 300 depending on response body
false: 422
URL: 201 if the resource is new, 303 otherwise

I will push that shortly.

@nevar nevar referenced this issue

Diagram for REST #364


Pushed 711c21a. Hope that's good.


Thank you


Closing, thanks!

@essen essen closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.