Possibility of optionally returning the resource with a create/update

[michaelm]

Hi all,

We're debating this at the moment - are there any best practices for allowing  a client to specify through the API that it wants the full resource back after the creation or update of a resource?

For example, we would always return the URL location and a 201 on resource creation. Some of the clients will simply end up requesting that URI immediately afterwards to retrieve the response. The same thing might happen on an update (I deliberately won't get into the POST/PUT debate here). Essentially what you are saying is I want this action, but the response to be the same as what I would retrieve if I called a GET directly afterwards on the response. Obviously they could achieve the same thing by issuing the GET themselves, but it makes for a less chatty API.

Would love to hear people's thoughts - thanks in advance.

Loving the group btw - really interesting topics and opinions!

[Ian Joyce]

My preference is to return the URI of the newly created resource in the Location header because it's what I expect as a consumer and that's how I interpret the http specification.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Michael McCarthy]

Hi Ian,

We'd certainly do that - we wouldn't want to veer away from the spec there. Question is, would it be wrong to make it up to the client if they also want the resource in the payload?

Thanks

--
You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/XvTLHONyTsw/unsubscribe?hl=en.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.

[Ian Joyce]

Personally I don't see a problem with including the created entity in the response. Especially if that's what your clients want. After all, what good is an API without clients?

[Mike Kelly]

There's absolutely nothing wrong with that from a technical point of view. Just make sure you include a Content-Location header if you do include the representation in the POST response so there's visibility that the response body represents the state of some other resource and not the target of the request.

Giving clients extra options does make your API slightly more complicated as it creates more for people to read in order to fully understand how it works. In this case its not much but I generally avoid giving clients any choice like that until they actually demand it - in order to keep the API as simple as possible.

Cheers,
M

[Jørn Wildt]

You might want to take a look at the proposed "prefer" header: http://tools.ietf.org/html/draft-snell-http-prefer-18

/Jørn

[Todd]

On Friday, 8 March 2013 07:01:03 UTC+13, Mike Kelly wrote:

There's absolutely nothing wrong with that from a technical point of view. Just make sure you include a Content-Location header if you do include the representation in the POST response so there's visibility that the response body represents the state of some other resource and not the target of the request.

Giving clients extra options does make your API slightly more complicated as it creates more for people to read in order to fully understand how it works. In this case its not much but I generally avoid giving clients any choice like that until they actually demand it - in order to keep the API as simple as possible.

Three questions:

1. would you return the resource or the representation? resource being effectively a copy of the POST data elements, representation being both the links and the data elements. I suspect you are meaning only the former
2. What effect is there on then NOT doing a GET on the representation? (ie that representation isn't yet cached in the network)
3. Is returning content on the 201 a simply an optimisation trade-off or is it something more complex? 

IMHO what looks like long-hand work (doing a GET on a 201 rather than assuming/retaining your content from the POST) will be part of a generalised and simpler implementation. 

Fourth question: has that been other's experience?

[David Biesack]

I've considered this as an option (and I actually did this for one service I created). I would recommend using the Accept: header. If there is none, just return the Location: header and an empty body. If the client requests a media type, then return the requested representation.

[Felipe Sere]

I agree with David on this. 

To me it's clearly a content negotiation aspect. 

If the client wants to get the resource as a specific representation, have him demand it via Accept. 

Then again, as long as you don't need it, there is no further benefit (except maybe caching...)

--

You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
Gruß,
Felipe

[Michael McCarthy]

Thanks all, really interesting answers and I like David's solution which makes sense. In the specific case we have come across there is data you would see in the GET that would not be in the POST, hence the need to lookup.

You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/XvTLHONyTsw/unsubscribe?hl=en.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.

[Mike Kelly]

Hi Todd,

On 7 Mar 2013 20:27, "Todd" <to...@goneopen.com> wrote:
>
>
> On Friday, 8 March 2013 07:01:03 UTC+13, Mike Kelly wrote:
>>
>> There's absolutely nothing wrong with that from a technical point of view. Just make sure you include a Content-Location header if you do include the representation in the POST response so there's visibility that the response body represents the state of some other resource and not the target of the request.
>>
>> Giving clients extra options does make your API slightly more complicated as it creates more for people to read in order to fully understand how it works. In this case its not much but I generally avoid giving clients any choice like that until they actually demand it - in order to keep the API as simple as possible.
>
> Three questions:
> would you return the resource or the representation? resource being effectively a copy of the POST data elements, representation being both the links and the data elements. I suspect you are meaning only the former

Yes, the former

> What effect is there on then NOT doing a GET on the representation? (ie that representation isn't yet cached in the network)

Pretty much, yep

> Is returning content on the 201 a simply an optimisation trade-off or is it something more complex?

As far as I can tell it is just an optimisation thing

Cheers,
M

[todd]

> would you return the resource or the representation? resource being effectively a copy of the POST data elements, representation being both the links and the data elements. I suspect you are meaning only the former

Yes, the former

> What effect is there on then NOT doing a GET on the representation? (ie that representation isn't yet cached in the network)

Pretty much, yep

> Is returning content on the 201 a simply an optimisation trade-off or is it something more complex?

As far as I can tell it is just an optimisation thing

 So, if I put all that together I see that an optimisation could lead to inconsistencies because we are returning a resource (GET) that hasn't come through a GET. This means we now have a representation of data elements that came with no links (and possibly headers). Of course, we can retrieve the links through a GET. (Perhaps, though, there could be a deeper design inconsistency. Our optimisation works more because our client knows in advance what is able to do with it?)