[VOTE] JSON-REST batching format

[Chris Chabot]

This is one of the two propose batching formats, the JSON-REST format
proposed by John Panzer.

The proposal can be read at :
http://groups.google.com/group/opensocial-and-gadgets-spec/msg/f923cf8c2283562d?hl=en

(john if you have a link to a docs.google.com document, please
contribute it since the formatting is lost in this link)

Please vote +1 If you prefer the JSON-REST proposal over the JSON-RPC
proposal. Otherwise vote on the other thread.

The proposal with the most votes will become the batching format for
the 0.8.1 spec, so please vote so we can accept one of these two since
either is much better then the 0.8 one, but please also do so after
having evaluated the pro's and con's for each since we'll be using it
for a long time to come.

[Chris Chabot]

Here's the link directly to the document:

http://docs.google.com/Doc?id=dc43mmng_23fdbpp7hd

[Scott Seely]

I like the REST version a bit better than the RPC one. REST allows us to
come up with a single way to identify the endpoints. RPC would require
us to come up with yet another spec on how to name things.

I have one concern with the REST spec: It assumes that correlation will
be done by position. As a result, a client has to remember things like
"the request to update a friend was item #1; the request to do something
else was item #2." When the response comes back, the client needs to use
this memory to decide which items are failures.

Proposed resolution: Batched responses need to include the method, and
URL of the original request to allow for correlation. This would also
allow for responses to come back unordered, as well as for some more
sophisticated container semantics (ex. javascript that handles the
batching by queuing requests over a predefined timespan). Assumption: a
matching method and URL could be processed by only looking at the last
matching method+url.

Example:

POST /batchOps HTTP/1.1
Authorization: OAuth realm="http://example.org/",
oauth_consumer_key="dpf43f3p2l4k3l03",
oauth_token="nnch734d00sl2jdk",
oauth_signature_method="HMAC-SHA1",
oauth_signature="tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D",
oauth_timestamp="1191242096",
oauth_nonce="kllo9940pd9333jh",
oauth_version="1.0"
Content-Type: application/json


[
{
"method" : "PUT",
"url" : "/people/@me/@all/example.org:3838923?fields=nickName",
"id" : "setContactNickName",
"body" :
{
"nickName" : "Flounder"
},
"If-Match" : "A35II835334339"
},
{
"method" : "GET",
"url" : "/people/@me/@friends"
},
]


Now generates:

HTTP/1.x 200 OK
Content-Type: application/json


[
{
"method" : "PUT",
"url" : "/people/@me/@all/example.org:3838923?fields=nickName",
"code" : 200,
"etag" : "B383999",
"id" : "setContactNickName"
},
{
"method" : "GET",
"url" : "/people/@me/@friends",
"code" : 200,
"ETag" : "XYZ3737",
"body" : {
"totalResults" : 100,
"startIndex" : 0,
"itemsPerPage" : 10,
"entry" : [
{..},
{..},
]


}


}
]


And this would also be valid:

[
{
"method" : "GET",
"url" : "/people/@me/@friends",
"code" : 200,
"ETag" : "XYZ3737",
"body" : {
"totalResults" : 100,
"startIndex" : 0,
"itemsPerPage" : 10,
"entry" : [
{..},
{..},
]


},
{
"method" : "PUT",
"url" : "/people/@me/@all/example.org:3838923?fields=nickName",
"code" : 200,
"etag" : "B383999",
"id" : "setContactNickName"
}

}
]

[John Panzer]

Query for Scott:  The RESTful batching proposal provides for a (client specified, string) id and makes it OPTIONAL for this purpose; the JSON-RPC proposal has exactly the same thing but makes it REQUIRED.  Is the id sufficient (in either case) to address your concern?  Or do you need something more (which isn't provided by either proposal right now)?

John Panzer (http://abstractioneer.org)

[Scott Seely]

It looks like I need to withdraw my concern—I missed that bit. (My apologies.)

 

So, after reading the proposal a few more times, I’ll raise a new concern.

 

I think we need to update the spec to state that responses MUST maintain ordering for batched requests.

 

Why?

1.       If id is not specified, then the results must come back in request order to allow for client side correlation.

2.       If id is specified on one item but not on others, the results must come back in request order allow for client side correlation.

3.       If id is specified on all items, we cannot require all ids to be unique. For example, imagine that someone passes in two items with the same id: a person and an activity. id values may have been derived from the ids in the system. To work with this possibility, we would again need to maintain ordering. Nothing prevents an implementation from deciding that a person and an activity can have the same id.

[Louis Ryan]

Scott,

The id's that John mentions are not the ids of the entities being addressed but rather an arbitrary client generated id which it can associate with the request and expect to be returned with the correlated response. So I think you're 3rd point below is not applicable and we could reasonable require these id's to be unique within a batch just as we do in the OpenSocial JS

-Louis

[Scott Seely]

My point was this: the spec needs to require that servers match request order with response order.

 

I took point #3 as an example of why this would be true, even in the presence of ids.

 

Given your requirement, we could make order unimportant for case #3. I don’t think we should add a uniqueness constraint on ids. Every server implementation will have to handle the case where responses must come back in order when ids aren’t present. Requiring the ids to be unique means that server implementations will have to write extra code to reject a request that is otherwise fine without the ids. Because that id is only meaningful to the client, what does a server gain by validating uniqueness? I argue that the server doesn’t gain anything.

[John Panzer]

I'd phrase it this way: "Order of operations in the response MUST be the same as in the request, unless all operations have client-provided ids." 

In the JSON-RPC variant, ids are required and used as keys in the response, so they MUST be unique to have a well-formed JSON response.

(This could be added to the JSON-REST variant too if people have strong feelings BTW, it's just that I imagine a lot of the unique IDs will look like {1,2,3,...} anyway.)

John Panzer (http://abstractioneer.org)

[Louis Ryan]

I completely agree that order should match between request batch and response batch. Order can be maintained when the result is an associative array or a regular array but if we want to use associative arrays as the result format we need to require unique id's

There are a couple of arguments for requiring unique id's
- Allows access of the batch result as an associative array using batchresult.<unique key> which means less code in general for clients
- Allows for using the output of one request as the input to a later one (subject to ordering). There have been a number of discussions on the value of joining in prior threads, the best use case being restricting app data to a paged subset of friends.
- A client can use the array of requests to do ordered iteration of an associative array of responses if needed, 'for each' style loops will also maintain iteration order on some platforms

The choices and trade-offs are pretty-much the same in either spec so its really about how we want clients to access the response.

[John Panzer]

John Panzer (http://abstractioneer.org)

On Wed, Jul 30, 2008 at 5:51 PM, Louis Ryan <lr...@google.com> wrote:

I completely agree that order should match between request batch and response batch. Order can be maintained when the result is an associative array or a regular array but if we want to use associative arrays as the result format we need to require unique id's

There are a couple of arguments for requiring unique id's
- Allows access of the batch result as an associative array using batchresult.<unique key> which means less code in general for clients
- Allows for using the output of one request as the input to a later one (subject to ordering). There have been a number of discussions on the value of joining in prior threads, the best use case being restricting app data to a paged subset of friends.
- A client can use the array of requests to do ordered iteration of an associative array of responses if needed, 'for each' style loops will also maintain iteration order on some platforms

All true, though note that the last two are really arguments for _allowing_ unique IDs to be sent from the client and requiring servers to honor them.  (You get all the benefits of the last two without needing to make it required on the client.)
 

[Scott Seely]

I’m leery of the ‘unless’ below.

 

As you point out in a fork of this thread:

“All true, though note that the last two are really arguments for _allowing_ unique IDs to be sent from the client and requiring servers to honor them.  (You get all the benefits of the last two without needing to make it required on the client.)”

 

And that was in response to Louis’ comment about why unique ids are valuable client side. I don’t think that a server should make assumptions about the uniqueness of the ids—just return things in order and echo back any ids. This would change the language to:

 

“Order of operations in the response MUST be the same as in the request. If operations have client provided ids, those ids must also be present in the same order as the requests.”

 

Is this OK?

[Paul Walker]

I favor the JSON-REST format over the JSON-RPC format, but I would also like to see support for x-www-form-urlencoded POST/PUT requests for single entity updates.  This allows us to sign the request body and I believe it what would be used in most instances of PUT/POST by developers.

 

Slammed w/ meetings the past couple of days, but I will follow up with more as soon as I can.

 

~Paul

[Chris Chabot]

Both the JSON-REST and JSON-RPC threads have seen a good bit of feedback, but both have only received one +1 vote (two when you count the champion for the proposal).

So far we have 3 people favoring the JSON-REST proposal (with John Panzer, Paul Walker & Scott Seely indicating they prefer it), with the JSON-RPC version of the proposal having Louis Ryan, Zhen Wang and Robert Evans indicating they prefer that solution.

In both actual votes and feedback these 2 proposals appear to be tied, so if anyone has an opinion about this or has something to contribute to either of the 2 proposals, is willing to be swayed either way or has any other suggestions on how to solve this stalemate please don't hold back :)

-- Chris

[Scott Seely]

In the light of two other items working their way through, OpenSocial Data Template and OpenSocial Data Pipelining, do we really need section 9 (request batching)? I think that Data Template and Data Pipelining offer a more elegant and appropriate solution to this problem because they open the door for evaluating scores of requests directly on the server as needed.

 

Further, while it would theoretically help process more requests faster, is there a real, demonstrated need for the batching feature?

[Chris Chabot]

Hi Scott,

The direct use case that i have in mind with the batching mechanism is the gadget js -> social data interface communication; Right now the shindig (both java and php) use a custom protocol to facilitate this, since doing round trips is very expensive from the client browser perspective, and the batching method in the spec wasn't ideally suited for this. While the data template/data pipelining does solve this for gadgets that use that, the classic JS API benefits greatly from having batching in place.

In this case it is of course possible to just leave that as it is (as an undocumented extension for shindig's javascript libraries), however there is a potential window of opportunity now to come up with a proper solution that is usable by anyone, so that it can also benefit the other use cases.

So in other words, if we already have -some- form of batching, wouldn't it make sense to document it and allow external parties use it through the RESTful API too? Even for server to server communication, when doing a lot of requests, it can save a good bit of overhead, and be consistent with how the JS API works.

-- Chris

[Scott Seely]

Thanks for explaining this. You’re right that if we are going to have this, we might as well be consistent across implementations. Thanks!

[Paul Walker]

Can you provide some exact use cases of batching from the gadget js?  Could not one resource URI be created that represents the multiple being batched?  For example, if there is a desire to batch both owner and viewer, rather than some complex form of batching multiple resources, couldn’t we create one resource URI that represented both (e.g. /people/owner,viewer?format=json)

 

~Paul

[Louis Ryan]

I think the problem here is composability. Most gadget developers fetch at minimum VIEWER, VIEWER_FRIENDS, OWNER, OWNER_FRIENDS & app-data for VIEWER and OWNER. There isn't really any good way to compose that set into a single identifiable resource. Many gadget developers also fetch a set of userid's that they have stored on the backed. As the APIs expand to include more types, the likelihood that we will create the permutation of possible individual calls as resources reduces and so I think we will inevitably come back to the batching question.

I completely agree that the pipelined pass through rendering with data fetching is a big improvement for gadgets but I dont think it obviates the need for batching for the reason Chirs outlined previously and because  we will be passing through the equivalent of a batch response to the gadget developers endpoint which will need formalization.

Chris , BTW I think Cassie was +1 on RPC too for your scorekeeping :)

[chabotc]

Pretty much any case where you want to retrieve a mix of activities &
person info for example.. see our activities sample gadget as a simple
example:
http://modules.partuza.nl/gadgets/files/samplecontainer/examples/SocialActivitiesWorld.xml

function refreshActivities() {
var req = opensocial.newDataRequest();
if (!viewer) {
req.add(req.newFetchPersonRequest('VIEWER'), 'viewer');
}
req.add(req.newFetchActivitiesRequest('VIEWER'),
'viewerActivities');
req.add(req.newFetchActivitiesRequest('VIEWER_FRIENDS'),
'activities');
req.send(handleActivities);
}

The whole basis of the js open social api is that you can add a lot of
mixed fetch requests to the request, and while it could perform a lot
of different fetches in the background before returning, that's not
very optimal. You can already mix in a couple of types:
http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.DataRequest
And as time goes on that list is bound to only expand.

[Paul Walker]

Our current version of our API supports multiple users simply by allowing the consumer to delimit the ids with semicolons (/users/{userid};{userid};{userid}…

).  Couldn’t we do the same thing with this spec?  This is what Sam Ruby recommends after all ;-). 

 

Naturally there are a number n of entities on any non-trivial API and as n grows there are more permutations, but the argument makes the large leap that all permutations need to be supported by the API.  I would argue just the opposite, that a permutation should not be supported unless a good use case for it exists, at which time, a resource should be defined for it.

 

Generic batching punts the responsibility of properly defining our resources (much like the fields parameters) and gives the consumer assumption that any requests can be batched even those that don’t make sense. 

 

~Paul

[Louis Ryan]

Paul,

There are a couple of things I disagree with in this line of reasoning. The hypothetical fetch-this-person-and-fetch-this-activity resource would return {<person>,<activity>}. Returning two different resources as part of an 'aggregate resource' without a standard as to what format that response should take is asking for incompatability. We can try to have a discussion on a case-by-case basis in the spec group every time we need to add another aggregate resource to the API but it just seems like that approach multiplies the effort of standardization, documentation, implementation and compliance.

The potential set of aggregate resources is'nt simply the permutation of the number of different entity types but the sum of all the permutations of the addressing modes of those types. That is already a large number and more endpoints than I would like to see supported.

The point that a generic batching mechanism implies to consumers that use-cases are supported when they aren't I think is not really an issue. We're already telling developers that an ordered sequence of API calls will work either partially or completely, we don't say anything different in batch. Generic batching allows us to focus on making a small set of APIs work well and consistently and simply letting consumers choose the best way to access them for their use cases.

-Louis

[Evan Gilbert]

+1 on JSON-RPC version.

They are very close right now, but I really like the method/params split as it creates a simple 1:1 mapping to client libraries. Method -> function name, params -> function params.

It is not a lot of work to map the JSON-REST data structure, but when you don't have a 1:1 mapping then people have to understand the variations, and you have opportunities for mistakes in the mapping.

Think there's a small enhancement that will help keep a tight link with REST URls as well. We should have a standard parameter in the {params{}} map for the REST entry, matching the {body{}} tag in the JSON-REST proposal. Think that both "body" or "entry" would be appropriate. With this, we have the following for a single entry

{
 id: 'someKeyForClient',
 method: 'people.put',
 params: {
   entry: {
    id: '123',
    name: 'OpenSocial Ophelia',
    email: 'f...@bar.com,
   }
   fields: ['name', 'email']
 }


The above would turn into:
    putPerson(entry: {id: '123', 'OpenSocial Ophelia', email: 'f...@bar.com'}, fields: ['name', 'email']).

If there is a CRUD style data store, we can automatically map entry to the update, and map ".put" to the update function:
    personDataStore.update({id: '123', 'OpenSocial Ophelia', email: 'f...@bar.com'}).

Evan

[Evan Gilbert]

+1 on keeping arbitrary batching. The permutations to support our existing APIs are too large - there is no URL format that will easily support a standard request for viewer, owner, viewer friends, owner friends, activities, and app data. Each of these requests has its own parameters, so we're looking at an impossible URL just to support the common use cases (it would be a batch, just by another name).

On Mon, Aug 4, 2008 at 2:47 PM, Paul Walker <pwa...@myspace.com> wrote:

[Chris Chabot]

The JSON-RPC format seems to be edging ahead (with 2 more votes then the REST based batching version), and i think we are all eager to get to a conclusion after 2 weeks of lively discussion.

For the clarity of process, do the proponents of the JSON-REST solution have any severe objections to the JSON-RPC format that would make them essentially vote -1 against it? If so it would be great if you could voice that in the course of the day, so we can keep this moving forward. 

If no strong objections / -1 votes are made, or an equal amount of new +1 votes for the JSON-REST format, we are probably able to call the JSON-RPC solution our new batching format tomorrow.

Thanks all for the feedback, input and votes so far; Keep it up we're almost there!

-- Chris

[John Panzer]

I think everyone agrees that the two proposals are very close to each other in terms of immediate practice, so we're down to 'style' and speculation about the future as guidelines for what the best approach is.  I won't put a -1 on the RPC mechanism as I think both approaches will work nearly equally well for the immediate problem.  I think the RESTful approach wins in the long term but it's not possible to demonstrate long term benefits in the short term, thus we're left with discussions.

I would ask the RPC advocates to do two things, if they would:

1. Address the mismatch between the RPC interface and the RESTful individual operation interface; Evan claims that the RPC is better because it reduces the cognitive gap between the batching protocol and today's implementations of the protocol, but it increases the gap between the batching protocol and the individual operations.  There seems to be a contradiction here and I don't understand it.

2. I've heard a lot of misconceptions about REST, and I'm a bit worried that people may be operating from different premises.  I've read the JSON-RPC 2.0 spec.  I'd ask people to take a look at at least the Wiki article on REST: http://en.wikipedia.org/wiki/Representational_State_Transfer .  Aside from the dicussions about caching (which is more important than the people doing private-data-only social networks thinks it is), REST standardizes the discovery, evolvability, and exentisibility model, which is an important long-term benefit.  So, please review and make absolutely sure you don't want this.

John Panzer (http://abstractioneer.org)

[Chris Chabot]

My previous post accidently ended up on the wrong thread:

I think what we are rapidly approaching here, is settling on a hybrid
approach.

There are a lot of people excited about the RESTful interface, but
there also those who think a RPC interface is a far better solution
and neither camp has been able to pull the other to their side in the
last 2 weeks.

As such currently it looks like we'll have both, a classic REST
interface for single requests, and a RPC interface too, which while it
can be construed as confusing, does cater to the desires of both sides
and does give the app developers the choice to which they prefer; Just
as long as they don't want to batch REST requests :)

So baring any -1's in the next 24 hours, i think we're ready to call
this a compromise and go for the (single request) RESTful service, and
a JSON-RPC service next to that.

-- Chris

[Paul Walker]

So, how do all of the other google apis get away without a batching mechanism?

 

Using a comma delimited list to separate identifiers on a list of entities in a URI is not meant to be a solution for batching GETs across entity types, but it is a better solution for batching gets of multiple records of the same entity type.  And this is exactly what I’m afraid of with this generic batching proposal, is that it is going be referred to and used when at times it would be better to ensure we properly define resources (and their response representations)

 

I concede that this batching proposal would be needed for if the desire is to get multiple resources of different types, but I would also argue that if a particular resource (such as an activity or a list of activities) always has the context of a user associated with the activities, then we could simply change the definition of the representation to include the user.  It’s very common to include the related parent entity when a request is made for a child in a hierarchal relationship.

 

I’m afraid most of the time in implementing this generic batching is going to be spent handling the combinations that should not be allowed.  Consideration of this should be considered outside of the context of Shindig and a particular containers implementation, but that’s a bit late I suppose.

[John Panzer]

For operations where you're doing the same thing to a _lot_ of data (GET, PUT, POST, DELETE) then using composite resources, even ad-hoc ones, works pretty well.  Kind of like a SIMD (Single Instruction Multiple Data) processor design, which scales pretty well, and for the same reasons.

The critical use case for having ad hoc batching was not scaling up to a lot of data, but the following type of scenario, initiated by gadget folks:

I want to do an update, followed by a retrieval of some resource that might have been affected by the update either directly or indirectly.  I therefore need to do the two in sequence (can't parallelize) and there's not necessarily an obvious composite resource to be dealt with.  A somewhat fanciful example here would be updating one's own geographic position, then retrieving the list of friends within five miles of one's current position.  I don't want to incur the cost of two HTTP round trips to do this.

If I could've figured out a way to deal with this as a composite resource I certainly would have :)  The closest I could come was to jump to a completely general "batch operation resource" that executes what's effectively a program on the server.

The other specific use case which Louis mentions, having servers batching up things like activity updates so they're not doing too many round trips, is actually better served by POSTing a collection of updates.

John Panzer (http://abstractioneer.org)

[Paul Walker]

Louis, Evan, Scott and I had a long discussion re: batching. 

 

I do some use cases where batching is useful, but my main concern is that I want to ensure that we don’t default to batching requests as a solution when a resource could define the operation.  Also, for GET requests of a list of entities of the same type, if we can create a resource that takes a delimited list of ids, I would prefer that (as discussed in another thread).  Also, I don’t see an issue with defining the response body to a POST/PUT to include the updated resource (along with the location header on a POST). 

 

So, I’m not opposed to batching (and see some value) as long as we do our due diligence and ask ourselves, “Could we define this operation as one resource?”  As far as the semantics of REST vs RPC, I still lean toward the former, with the understanding that it may be a tad more difficult to parse the parameters out of the body of the entity.

 

We discussed support for x-www-form-urlencoded and mutipart/form-data for single entity PUT/POST as well.  I’ll start another thread specific to that.

[Chris Chabot]

Ok guys, it's time to choose one of the two proposals so we can get this show on the road and start the work on getting this out there.

Currently the JSON-RPC proposal has received 4 votes, and the REST-RPC one has received 3. I'm willing to add my own +1 to the JSON-RPC one to be able to finalize this round. Neither proposal has received any -1's and it looks like there's no blockers remaining.

So lets call this the last 24 hours before we close this thread and declare the JSON-RPC proposal the winner and the batching format in the 0.8.1 specification. Then we'll have had 3 weeks to sort this out, which should have been ample of time to raise any objections, so I don't really expect any surprises :)

Thanks to all for the hard work and effort put into this,

-- Chris

ps, Paul, lets try to get a thread going on the x-www-form-urlencoded soon so we can try to get convergence on that before 0.8.1 is fully done; I'm a bit hesitant to draw out this already quite long process even more so the sooner the better :)

[Krishna Sankar (ksankar)]

+1 for JSON-RPC

[Krishna Sankar (ksankar)]

Couple of thoughts:

a)      I think we are talking about a heterogeneous batching viz: composite data

b)      If so, would it be a good idea to embed the  operation in the batch separator ? (I think that is what Paul is talking about)

c)       Agree with Paul that we should try to use REST semantics as far (and much) as possible

d)      More import question is “How does REST handle heterogeneous batch operations ?”. Do we need to extend REST ?

e)      Would be happy to participate in an f2f form (or visit cubicles ;o)) if needed.

Cheers

<k/>

[John Panzer]

Krishna -- Don't want to muddy the waters further, but your points (c) and (d) makes me wonder why you're not +1 on the alternative REST batching proposal?  (Or if you're not +1 on it, why specifically, since it addresses (a)-(d) below AFAICT.)

John Panzer (http://abstractioneer.org)

[Chris Chabot]

Well we've given this a lot of time to cook and get ready, and by all appearances it seems as if everything has been said about the JSON or REST based approach; As such it's time to close this thread, and after 3 1/2 weeks, we are ready to declare the JSON-RPC proposal the winner (by a slight margin)

I hope we can all now lay this part of the discussion to rest (pun intended), and focus on making the best JSON-RPC API we can.

Thanks everyone for the patience, input and discussions, we're one step closer to having a new and improved 0.8.1 spec!

-- Chris

[Louis Ryan]

One remaining order of business. We need to state whether support for this in the spec is a MAY/SHOULD.

Not that it makes much difference but any objections to SHOULD?

[John Panzer]

Just for context with these IETF terms...

A MAY means an implementation is free to do something (and for
compatibility, everybody else needs to be aware of the possiblility).

A SHOULD means that an implementation has to implement something
unless there's a really good reason not to. Things like security
problems or major performance issues where the community agrees to
ignore the standard for example.

[Scott Seely]

+1 for MAY

MySpace users have not shown any need for batching and we have no
intention to support the feature at this time.

-----Original Message-----
From: opensocial-an...@googlegroups.com
[mailto:opensocial-an...@googlegroups.com] On Behalf Of John
Panzer
Sent: Wednesday, September 03, 2008 10:19 AM
To: opensocial-an...@googlegroups.com
Subject: Re: [VOTE] JSON-REST batching format

[Evan Gilbert]

I'd prefer to make this a SHOULD and assume that we're all working towards building the optional extensions, just not in the immediate time frame.

Also, in practice JSON-RPC will be available on most containers as support is being committed to Shindig for both Java and PHP.

So +1 for SHOULD, but I'm not sure if it matters much.

Evan

[Scott Seely]

MAY is what we are stating in this thread. We are not even in the spirit of a ‘SHOULD’. Please understand that RFC2119 means some very specific things. This isn’t like “you should brush and floss daily”. We are clearly demonstrating the behavior of a ‘MAY’. ShinDig thinks this will help, MySpace says ‘no.’ That’s a MAY, according to RFC2119.

 

 

From http://tools.ietf.org/html/rfc2119:

 

3. SHOULD This word, or the adjective "RECOMMENDED", mean that there

   may exist valid reasons in particular circumstances to ignore a

   particular item, but the full implications must be understood and

   carefully weighed before choosing a different course.

 

 

5. MAY This word, or the adjective "OPTIONAL", mean that an item is

   truly optional.  One vendor may choose to include the item because a

   particular marketplace requires it or because the vendor feels that

   it enhances the product while another vendor may omit the same item.

   An implementation which does not include a particular option MUST be

   prepared to interoperate with another implementation which does

   include the option, though perhaps with reduced functionality. In the

   same vein an implementation which does include a particular option

   MUST be prepared to interoperate with another implementation which

   does not include the option (except, of course, for the feature the

   option provides.)

 

 

Scott Seely

architect

email  sse...@myspace.com

[Krishna Sankar (ksankar)]

Agreed. OPTIONAL is MAY. Remember, a time will come when we need to worry about conformance et al and at that time this would be important.

 

Cheers

<k/>

 

From: opensocial-an...@googlegroups.com [mailto:opensocial-an...@googlegroups.com] On Behalf Of Scott Seely
Sent: Wednesday, September 03, 2008 3:28 PM
To: opensocial-an...@googlegroups.com
Subject: RE: [VOTE] JSON-REST batching format

 

MAY is what we are stating in this thread. We are not even in the spirit of a ‘SHOULD’. Please understand that RFC2119 means some very specific things. This isn’t like “you should brush and floss daily”. We are clearly demonstrating the behavior of a ‘MAY’. ShinDig thinks this will help, MySpace says ‘no.’ That’s a MAY, according to RFC2119.

[Paul Walker]

+1 on MAY

[Chad Russell]

+1 on MAY also

[Cassie]

+1 on MAY

[Louis Ryan]

It seems like there's consensus on MAY so lets use that then....

[Evan Gilbert]

Scott's explanation made sense. I'm good with MAY as well.

I think the MAYs have it.