Partial Responses.... worth it?

[Richard Berger]

Just started implementing partial responses and I was interested in hearing opinions as to when these are most useful. 

For concreteness, I am working with the following:

/userActs - returns a history of all the acts taken, each userAct has several fields (timestamp, actTaken, commentText)

I was thinking that it might be useful to have /userActs/?fields=commentText to get a list of all the comments (e.g. a "comment history")

Fortunately, this was pretty easy to implement using Jackson and a very helpful link at http://stackoverflow.com/questions/9314735/how-to-return-a-partial-json-response-using-java

Having implemented it, I began to wonder if it was really worth it.  I tried to take the client perspective - in this particular case, a google gadget.  When I return a list of UserAct objects, the client code to display them is:

          if (key == "userActs") {

            html += "<br /><ul>";

            for (var i = 0; i < value.length ; i++) {

              html += "<li>"+ jsondata.userActs[i].commentText + "</li>";

            }

            html+= "</ul>";

When I return a list of Strings (just the commentText), the code is:

if (isFinite(key)) {

  var commentTextObj = JSON.parse(value);

  html += "<li>"+ commentTextObj.commentText + "</li>";

}

In the first case, the JSON data being returned is:

[

  {

    "id": 68001,

    "commentText": "sure thing",

    "date": 1336025685984,

    "canonicalName": "P_Agree",

    "displayName": "Agree",

    "uri": "/commitment/67001/userAct/68001"

  },

.....

  {

    "id": 73001,

    "commentText": "from the gadget",

    "date": 1336329796148,

    "canonicalName": "P_Deliver",

    "displayName": "Deliver",

    "uri": "/commitment/67001/userAct/73001"

  }

]

In the second case it is:

[

  "{"commentText":"sure thing"}",

....

  "{"commentText":"from the gadget"}"

]

So as to whether Partial Responses are worth it...

* Pro: Easy to implement, Client might want to use it, Could perform better if UserData object becomes very large, Expected in REST APIs (?)

* Con: Extra documentation required, could confuse users (is the list of Strings a standard response?), extra testing required, don't spend time on performance enhancements before the problem exists.

Thoughts?  Recommendations?  Experiences?

<Trying really hard to avoid puns based on the phrase "partial respons-ibility">

Thanks all,

RB

 

[Daniel Roop]

We use it a lot because we also have the ability to expand links server side.  This ends up creating large resources very fast if you are doing it on lists.  So our clients in limited bandwidth or where bandwidth is expensive like mobile phones we use partial response to shrink the message before it leaves our network.  This of course doesn't speed up the request in fact it may slow it down since it is extra processing but it does reduce the payload which is desirable in some situations.

Daniel Roop

[Arlo Belshee]

OData also includes narrowing projection. This is commonly used, again to support bandwidth-constrained clients.

 

Some OData implementations actually push the projection all the way down into the data tier (obviously, only the ones backed by relational data stores do this). In these implementations, restricting the returned columns actually reduces both server processing time and client bandwidth.

 

As Daniel said, select becomes critical as soon as you have expand (inline expansion of linked resources). Without expand it only matters if you have some fat resources (e.g., resources with inline large strings such as XML documents).

 

Arlo

[Richard Berger]

Thanks all - I am most persuaded by the facts that:

a) Inline expansion of linked resources can get big

b) Implementation is actually pretty simple

One follow-up question (although this may be more specific to Jackson than generic) - is returning a list of strings reasonable when the URL has specified a set of fields rather than an entire object?

Thanks again,

RB