201 vs. 204 status codes

[nickdu]

I'm wondering what status code to return from a post to one of my collections.  This is just a sample I'm working on.  The collection is there to support a "transfer" action between accounts.  So if I want to transfer money from account /accounts/savings to /accounts/checking I would post the from and to account and the amount to the /transfers collection.  I'm wondering what status code to return from this post?  It seems if I return a 201 I might need to include a representation in the response.  I was thinking that there might be no need for a representation for this request.  My thinking is the client just wants to know whether it was successful and if so any link to any resource that was created.  So would it be valid to return a 204 with the Location header set?

Thanks,
Nick

[Kijana Woodard]

Two thoughts.

Consider modeling the "transaction" explicitly. Having the "transfer history" around might be useful.

Consider 202 Accepted.

--
You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hypermedia-we...@googlegroups.com.
To post to this group, send email to hyperme...@googlegroups.com.
Visit this group at http://groups.google.com/group/hypermedia-web.
For more options, visit https://groups.google.com/d/optout.

[nickdu]

Thanks.  I was thinking that it would be useful to keep for some amount of time.  Since I would most likely be able to return the URL for the newly created resource from the POST it seemed reasonable to do that.  However, since it seems less likely that someone might want to act on it I thought it best to return the URL only and no representation.  I therefore thought a 204 was the most appropriate, but wasn't sure.  202 is more for asynchronous actions, correct?  One in which I would not be returning a resource URL from the POST, or can you still return the URL?

Thanks,
Nick

[Kijana Woodard]

I was thinking of it as "asynchronous" in that the "transfer resource" is [probably] not the one you're interested in. You [probably] want to next look at the "from" or the "to" account. 

From your statements, I assume you're assuring transactional integrity between the two accounts. You can choose not to leak that knowledge to your clients and give yourself room for growth [no idea what your domain demands]. The transfer resource can have a progress/status plus links to the accounts.

If none of that resonates, I would lean towards 201 and have the transfer resource have links to the accounts.

I'm partial to returning links [location header] from post/put instead of full resources, but I'm slightly ocd about having multiple ways of obtaining a resource. 

[Joe Kowalski]

Just some addition info on how we handle this. Every request that is NOT a GET returns an [actionStatus]. A Status 200 or 201 will contain the following [actionStatus] (example in json of course).

 

{header:{

    actionStatusID:’e747ff45-6d7b-4bfc-8dd7-dbf8ea1ebfd5’,

    status:’Complete’,

    percentComplete:100,

    message:’Record Created’},

data:{

    [payload]

}}

 

Just some addition info on how we handle this. Every request that is NOT a GET returns an [actionStatus]. A Status 202will contain the following actionStatus.

 

{header:{

    actionStatusID:’e747ff45-6d7b-4bfc-8dd7-dbf8ea1ebfd5’,

    status:’Pending’,

    percentComplete:0,

    message:’Request Received’},

links:[{

id:’status-check’,

method:’GET’,

url:’http:// mydomain.com/api/actionStatuses/e747ff45-6d7b-4bfc-8dd7-dbf8ea1ebfd5’}]

}

 

 

~Joe

ServiceMonster|Principal Focus, LLC

888-901-3300|(206) 905-7796
Fax : 866-507-9375

[nickdu]

To be honest, this is just an example I'm creating for a pattern document on how to implement "actions" restfully so while I want it to be accurate, it's not something that I'm actually implementing so take that into account.

I'm still wondering whether it's valid to return a 204 and set the Location header to the transfer resource.  The thinking behind this is that most of the time the client would only be interested in knowing whether it was successful or not and not really interested in inspecting the transfer representation so why bother including it in the response.

Thanks,
Nick

[Kijana Woodard]

An opinion: http://blog.ploeh.dk/2013/04/30/rest-lesson-learned-avoid-204-responses/

I stipulate that you mentioned the Location Header for the link.

[nickdu]

I had read that article and didn't think much of it.  If I get a 204 it would seem I don't have to throw away my state, I just stay in the same state I was in.

Thanks,
Nick

[Kijana Woodard]

I'm not convinced that the client should be "stateless" in that way. What if the client interacts with multiple server applications?

204 seems a bit "harsh" to me, but I don't have a concrete rationale to oppose it [given a location header].

[come...@comcast.net]

On Thursday, March 12, 2015 at 11:14:41 AM UTC-7, nickdu wrote:

To be honest, this is just an example I'm creating for a pattern document on how to implement "actions" restfully so while I want it to be accurate, it's not something that I'm actually implementing so take that into account.

I'm still wondering whether it's valid to return a 204 and set the Location header to the transfer resource.  The thinking behind this is that most of the time the client would only be interested in knowing whether it was successful or not and not really interested in inspecting the transfer representation so why bother including it in the response.

Yes, all 2xx response codes are potentially valid for a POST request except for status code 206. See [1] for POST semantics and [2] for HTTP response code semantics.

[1] https://tools.ietf.org/html/rfc7231#page-25
[2] https://tools.ietf.org/html/rfc7231#page-51

Regards
Jeff Michaud

[Pedro Santos]

It's optional to include a body with a 201 Created so you don't *need* to return a representation with 201 Created. Although if you include a location header then the representation of that resource could be very well be placed in the 201 response (even if the client does nothing with it). I've also seen situations when the API even give the client the option of whether it want's the representation back or not via headers or query params.


@Kijana Very cool blog post post about 204, never had though about the loss of context a 204 causes (some of those things that are immediately obvious once someone points them out but never crossed your mind until then!). Thx for the link.

[come...@comcast.net]

@Kijana Very cool blog post post about 204, never had though about the loss of context a 204 causes (some of those things that are immediately obvious once someone points them out but never crossed your mind until then!). Thx for the link.

Hmmm, I'm not sure I agree with conclusion reached wrt to the loss of context. The semantics of 204 specifically indicates:

6.3.4 204 No content

"

The 204 response allows a server to indicate that the action has been
   successfully applied to the target resource, while implying that the
   user agent does not need to traverse away from its current "document
   view" (if any).  The server assumes that the user agent will provide
   some indication of the success to its user, in accord with its own
   interface, and apply any new or updated metadata in the response to
   its active representation.

"

This would translate in my mind to a client simply treating this response code as a success message from the server and nothing more. The client would otherwise not transition from where it's already at.

See https://tools.ietf.org/html/rfc7231#page-53

Regards
Jeff Michaud

[Kijana Woodard]

My guess is the problem involves the idea of a stateless client that would be "lost" without context.

Now whether clients *should* be stateless is another matter...

--

[come...@comcast.net]

On Friday, March 20, 2015 at 11:16:31 AM UTC-7, Kijana Woodard wrote:

My guess is the problem involves the idea of a stateless client that would be "lost" without context.

Now whether clients *should* be stateless is another matter...

Seems like a reasonable guess. Clients and Servers can have a state under REST, it's only a very specific aspect (communication) that's stateless :).

See http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1 section 5.1.3.

We next add a constraint to the client-server interaction: communication must be stateless in nature, as in the client-stateless-server (CSS) style of Section 3.4.3 , such that each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client. ... Like most architectural choices, the stateless constraint reflects a design trade-off. The disadvantage is that it may decrease network performance by increasing the repetitive data (per-interaction overhead) sent in a series of requests, since that data cannot be left on the server in a shared context. In addition, placing the application state on the client-side reduces the server's control over consistent application behavior, since the application becomes dependent on the correct implementation of semantics across multiple client versions.

Regards
Jeff Michaud

[nickdu]

Yes, I had the same impression as you.  A 204 means the request was successful and since no new state is returned you stay in the state you were in.  I don't see a problem.

Thanks,
Nick