Google APIs and JSON-RPC
Louis Ryan
JSON-RPC version
The specification sections 4 & 5 mandates that the value“jsonrpc” : “2.0”
be provided at the top-level of every request and response. In our case all our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so while we’re happy to accept it on input, and even reject requests that specify a value other than “2.0” we don't reject requests that omit this value and we do not populate it in the output.
Absence of ‘id’ to indicate that no response should be produced
The specification section 4 defines any request that does not contain an ‘id’ to be a ‘notification’. A notification is a request the response to which the caller does not care about and so the system should not produce a response object. In the case of a batch of requests this would mean that the cardinality of the batch response may not necessarily match that of the request. Our current behavior is to always produce a response even if an id is omitted primarily because even if something is dispatching an asynchronous job there is still the need for parameter validation which should be confirmed to the caller. Does anyone make significant use of the behavior described in the spec of perceive any performance advantage from it?Error code alignment
We produce codes per the specification for:-32700 - Invalid JSON
-32600 - Invalid request object
-32601 - Method not found. Instead we use the HTTP code 404 NOT FOUND
-32602 - Invalid parameters. Instead we use the HTTP code 400 BAD REQUEST
-32603 - Internal error. Instead we use the HTTP code 500 INTERNAL SERVER ERROR for failures in the Apiary stack and the spec code for failures caused by backend errors.
This variance is maintained primarily for compatibility with the OpenSocial JSON-RPC implementation in Apache Shindig which followed the same pattern. I think the error codification in the spec is one of its weaker areas about which there is good discussion on one of the other threads here. We use the 'data' field inside an error response to carry an array of more detailed error objects as our system allows for APIs to report secondary errors.
apiVersion:
The specification doesn’t provide a mechanism for describing different versions on the same API. We added support for this by defining an ‘apiVersion’ field at the top level of the request which contains a string literal of the version name. E.g{
id : ‘12345’,
method : “language.diacritize.get”,
apiVersion : ‘v2’
...
}
We do not currently echo back the apiVersion in the response and it’s worth discussing whether we should do so particularly when no apiVersion is specified in the request and the server chooses one by default.
Max Kanat-Alexander
> The specification sections 4 & 5 mandates that the value
> “jsonrpc” : “2.0”
I agree that this is wasteful and probably unnecessary in the response.
I have a server system that supports 1.0, 1.1, and 2.0, so if this
field is in requests, it's the simplest way for my system to understand
what sort of response the client wants.
If a client supports multiple versions, having it in the response helps
the client understand how it should parse the response (particularly for
errors, although the JSON-RPC specs *can* all be compatible with each
other in error formats, theoretically).
> In our case
> all our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so
> while we’re happy to accept it on input, and even reject requests that
> specify a value other than “2.0” we don't reject requests that omit this
> value and we do not populate it in the output.
I think that more or less, it's safe to ignore it. In my current server
implementation, I just assume that a request is 2.0 if it doesn't
specify otherwise, as well.
> The specification section 4 defines any request that does not contain an
> ‘id’ to be a ‘notification’.
I agree that this is useless and unfortunate--I wrote to the list about
it a few months back, also.
> however we vary from the spec by default for the following codes:
> -32601 - Method not found. Instead we use the HTTP code 404 NOT FOUND
> -32602 - Invalid parameters. Instead we use the HTTP code 400 BAD REQUEST
> -32603 - Internal error. Instead we use the HTTP code 500 INTERNAL
> SERVER ERROR for failures in the Apiary stack and the spec code for
> failures caused by backend errors.
I think that's pretty much in line with the JSON-RPC Over HTTP spec, no?
> We do not currently echo back the apiVersion in the response and it’s
> worth discussing whether we should do so particularly when no apiVersion
> is specified in the request and the server chooses one by default.
Mmm, since your APIs are centralized, I don't think anybody's going to
be implementing a client that attempts to support more than one API
version at once, right? If there are identical methods across different
APIs that would possibly get updated separately, though, there might be
a value in specifying the apiVersion in the response.
-Max
--
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.
Gaetano Giunta
Folks,
As announced at Google I/O were working on launching JSON-RPC support for most of our newer APIs. We've had success with using JSON-RPC for the client with OpenSocial so we are broadening our support for it. In particular JSON-RPC has proven useful as a dispatch mechanism for it's very obvious batch support and naming and parsing conventions that work well in Javascript clients. This by no means indicates that we are abandoning RESTful APIs or that we design first as RPC, quite the opposite in fact. It's simply that for newer APIs we support there is no reason to limit ourselves and our clients to a single transport mechanism for all use cases.�
There are a few areas where we are just non-compliant and have some questions about the value of what the spec is requiring. Let me know what you think as we'd like to launch fairly soon and we're very interested in the communities feedback.
CheersLouis
JSON-RPC version
The specification sections 4 & 5 mandates that the value
�jsonrpc� : �2.0�
be provided at the top-level of every request and response. In our case all our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so while we�re happy to accept it on input, and even reject requests that specify a value other than �2.0� we don't reject requests that omit this value and we do not populate it in the output.
Absence of �id� to indicate that no response should be produced
The specification section 4 defines any request that does not contain an �id� to be a �notification�. A notification is a request the response to which the caller does not care about and so the system should not produce a response object. In the case of a batch of requests this would mean that the cardinality of the batch response may not necessarily match that of the request. Our current behavior is to always produce a response even if an id is omitted primarily because even if something is dispatching an asynchronous job there is still the need for parameter validation which should be confirmed to the caller. Does anyone make significant use of the behavior described in the spec of perceive any performance advantage from it?
Error code alignment
We produce codes per the specification for:
-32700 - Invalid JSON
-32600 - Invalid request object
however we vary from the spec by default for the following codes:
-32601 - Method not found. Instead we use the HTTP code 404 NOT FOUND
-32602 - Invalid parameters. Instead we use the HTTP code 400 BAD REQUEST
-32603 - Internal error. Instead we use the HTTP code 500 INTERNAL SERVER ERROR for failures in the Apiary stack and the spec code for failures caused by backend errors.
This variance is maintained primarily for compatibility with the OpenSocial JSON-RPC implementation in Apache Shindig which followed the same pattern. I think the error codification in the spec is one of its weaker areas about which there is good discussion on one of the other threads here. We use the 'data' field inside an error response to carry an array of more detailed error objects as our system allows for APIs to report secondary errors.
- location and name of invalid parameters- textual namespaced error codes (see the other thread for discussion)- debug information and identifiers for request tracing- help links to reference documentation if requested
apiVersion:
The specification doesn�t provide a mechanism for describing different versions on the same API. We added support for this by defining an �apiVersion� field at the top level of the request which contains a string literal of the version name. E.g
{
�id : �12345�,
�method : �language.diacritize.get�,
�apiVersion : �v2�
...
}
This change looks the most "hard" to implement in generic jsonrpc clients (or the more specific one).
Could you not simply put that field as 1st (or last) element in the name of the functions themselves, eg: language.diacritize.get.v2 ?
We do not currently echo back the apiVersion in the response and it�s worth discussing whether we should do so particularly when no apiVersion is specified in the request and the server chooses one by default.
--
You received this message because you are subscribed to the Google Groups "JSON-RPC" group.
To post to this group, send email to json...@googlegroups.com.
To unsubscribe from this group, send email to json-rpc+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/json-rpc?hl=en.
Henry Unger
With respect to Louis Ryan’s comments:
Absence of ‘id’ to indicate that no response should be produced
The specification section 4 defines any request that does not contain an ‘id’ to be a ‘notification’. A notification is a request the response to which the caller does not care about and so the system should not produce a response object. In the case of a batch of requests this would mean that the cardinality of the batch response may not necessarily match that of the request. Our current behavior is to always produce a response even if an id is omitted primarily because even if something is dispatching an asynchronous job there is still the need for parameter validation which should be confirmed to the caller. Does anyone make significant use of the behavior described in the spec of perceive any performance advantage from it?
We use such notifications extensively for client/server applications where the server asynchronously notifies the client of state changes of other clients of the server. These state changes are published to all clients. There is no benefit in having the clients respond to the server notifications, and performance would suffer if the server had to field responses from each of the clients, especially when the the server is pushing notifications every second or two to each of a thousand clients. In addition, in a common carrier mobile environment where the carrier charges for traffic, or traffic in excess of a monthly limit, producing a response to the notification may double the cost or possibly worse.
Best regards,
Henry Unger
Hitech Systems, Inc.
Lorenzo Pastrana
Folks,
As announced at Google I/O were working on launching JSON-RPC support for most of our newer APIs.
There are a few areas where we are just non-compliant and have some questions about the value of what the spec is requiring. Let me know what you think as we'd like to launch fairly soon and we're very interested in the communities feedback.
JSON-RPC version
The specification sections 4 & 5 mandates that the value
“jsonrpc” : “2.0”
be provided at the top-level of every request and response. In our case all our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so while we’re happy to accept it on input, and even reject requests that specify a value other than “2.0” we don't reject requests that omit this value and we do not populate it in the output.
JSON-RPC 2.0 has (wery few but some) antecedents in 1.0 :
>From the specs, 3 - Compatibility :
JSON-RPC 2.0 does not work with JSON-RPC 1.0 clients or servers.
[snip]it is easy to distinguish between the two versions as 2.0 always has a member named "jsonrpc" with a String value of "2.0" whereas 1.0 does not[snip]
The term "Compatibility" in that paragraph is intended "backward" and that's the only place where it was addressed (in an implicit way thus). Fact is that "the future's not ours to see" ... and neglecting that could turn in an unforeseen bullet heading slowly toward your foot ...
The jsonrpc member requirement is mostly intended for future compatibility, and future compatibility has been a strong concern all along the specs elaboration. Chances are that you'll be blessing that 10 bytes spent someday.
Absence of ‘id’ to indicate that no response should be produced
In the case of a batch of requests this would mean that the cardinality of the batch response may not necessarily match that of the request.
I'd consider the cardinality of a batch being actually N - number_of_notifications
Our current behavior is to always produce a response even if an id is omitted primarily because even if something is dispatching an asynchronous job there is still the need for parameter validation which should be confirmed to the caller.
How an asynchronous client could ever dispatch a response without a request ID ?
Does anyone make significant use of the behavior described in the spec of perceive any performance advantage from it?
When the player takes an action that could fail the client would use a request ID and hope for a response.
Error code alignment
See the thread running ...
apiVersion:
The specification doesn’t provide a mechanism for describing different versions on the same API.
We added support for this by defining an ‘apiVersion’ field at the top level of the request which contains a string literal of the version name. E.g
{
id : ‘12345’,
method : “language.diacritize.get”,
apiVersion : ‘v2’
...
}
Why not :
{
id : ‘12345’,
method : “v2.language.diacritize.get”,
...
}
Or just a specific entry point ?
v2.some.api.server.google.com/call
{
id : ‘12345’,
method : “language.diacritize.get”,
}
Cheers,
Lorenzo
Dave
on a few of your comments:
-Notifications / id field / batch requests:
I think notifications are very valuable as one-way, low-overhead
requests. It's a unique and cool feature that json-rpc has that most
RPC systems do not. As far as batch requests go, as Lorenzo mentioned,
the # of responses is simply equal to the number of non-notification
requests in the batch. Quite easy to count if you need to match up
that sort of thing. The responses can come back in the batch in any
order, so "ordering" of the requests/responses and gaps from
notifications never enters the picture.
-Error codes:
I think my views on this are clear from the other thread, but I'd be
interested to hear your perspective on allowing error code to be a
string field instead of numeric. Obviously it could still be used with
numeric codes (for HTTP errors for example) but in terms of your API
errors, wouldn't you prefer to be able to give specific error code
responses from each application rather than using a 500 response for
every application error then burying the details in the data field?
-API versions:
I don't really see a need to embed version information at the
individual request level. If you want to have multiple versions of a
method available on the same endpoint, using method names with
versions seems reasonable, however I generally prefer the approach of
giving each version of the API it's own endpoint, which is the
approach used by most web services these days. Given that there is no
concept of "api versions" defined or described in the spec, I think
it's a rather heavyweight concept to add just to allow multiple method
signatures with the same name (which is the net result of your
suggestion).
-Dave
> I/O<http://code.google.com/events/io/2010/sessions/how-google-builds-apis...>were
> We've
> had success with using JSON-RPC for the client with OpenSocial so we are
> broadening our support for it. In particular JSON-RPC has proven useful as a
> dispatch mechanism for it's very obvious batch support and naming and
> parsing conventions that work well in Javascript clients. This by no means
> indicates that we are abandoning RESTful APIs or that we design first as
> RPC, quite the opposite in fact. It's simply that for newer APIs we support
> there is no reason to limit ourselves and our clients to a single transport
> mechanism for all use cases.
>
> There are a few areas where we are just non-compliant and have some
> questions about the value of what the spec is requiring. Let me know what
> you think as we'd like to launch fairly soon and we're very interested in
> the communities feedback.
>
> Cheers
> Louis
> be provided at the top-level of every request and response. In our case all
> our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so while
> we’re happy to accept it on input, and even reject requests that specify a
> value other than “2.0” we don't reject requests that omit this value and we
> do not populate it in the output.
> Absence of ‘id’ to indicate that no response should be producedThe
> specification section 4 defines any request that does not contain an ‘id’ to
> be a ‘notification’. A notification is a request the response to which the
> caller does not care about and so the system should not produce a response
> object. In the case of a batch of requests this would mean that the
> cardinality of the batch response may not necessarily match that of the
> request. Our current behavior is to always produce a response even if an id
> is omitted primarily because even if something is dispatching an
> asynchronous job there is still the need for parameter validation which
> should be confirmed to the caller. Does anyone make significant use of the
> behavior described in the spec of perceive any performance advantage from
> *Error code alignmentWe produce codes per the specification for:
Max Kanat-Alexander
> We use such notifications extensively for client/server applications
> where the server asynchronously notifies the client of state changes of
> other clients of the server.
So, I've been thinking about this, because I'm not opposed to
notifications--I'm simply opposed to the semantics of "no id means this
is a notification".
Instead of this, why don't we include a field "notification: true" that
means "this SHOULD NOT get a response"?
That would preserve notification functionality while allowing the
majority of requests to be simpler by not containing an id.
Derrell Lipman
Instead of this, why don't we include a field "notification: true" thatmeans "this SHOULD NOT get a response"?
That would preserve notification functionality while allowing the
majority of requests to be simpler by not containing an id.
Henry Unger
Given that responses may be asynchronous and unordered, I agree that having the id field should be mandatory when a response is expected, otherwise it would be impossible for a client to correlate a response with its request at the protocol level. From a conceptual basis, I have been taking advantage of this type of behavior (presence of id means response, absence means notification) for almost 25 years in public safety applications.
Henry Unger
Max Kanat-Alexander
> An id allows the responses to multiple async requests to be
> associated with their request when the response is received. If no id is
> sent with a request that requires a response, only one could be sent at
> a time or there would be no way to correlate the responses to their
> requests.
That's true, but:
(a) I've never needed the id. For example, I'm often using the YUI
DataSource module, which keeps track of requests separately. In fact,
any good async framework keeps track of requests and responses in some
way of its own.
and
(b) It's essentially putting an implementation detail into a protocol spec.
So what I'm saying is that I'd like it to simply be optional.
Derrell Lipman
On 09/04/2010 07:52 AM, Derrell Lipman wrote:That's true, but:
> An id allows the responses to multiple async requests to be
> associated with their request when the response is received. If no id is
> sent with a request that requires a response, only one could be sent at
> a time or there would be no way to correlate the responses to their
> requests.
(a) I've never needed the id. For example, I'm often using the YUI
DataSource module, which keeps track of requests separately. In fact,
any good async framework keeps track of requests and responses in some
way of its own.
and
(b) It's essentially putting an implementation detail into a protocol spec.
Max Kanat-Alexander
> Hmmm... I'm not convinced. There needs to be some way to associate a
> particular response with the request which is being responded to.
Yeah, I agree, and it should be optional. If I personally don't need a
way to associate requests with responses, then why force me to include
the id?
> The client side (or whomever is
> the issuer of the request) would need to be customized for each server
> it wants to make requests of.
Yes, if there wasn't an id field at all in the spec, that would be
true. But there is an id field, I just want it to be optional.
> I believe that having the id field as part of every request and response
> (with the possible exception of the special type of request called a
> notification) adds to the standardization that allows clients to be
> used with multiple servers.
Notifications would also work with a "notification: true" field.
Burak Yiğit KAYA
Sean Kinsey
implementation agnostic protocol, both when it comes to the endpoint
implementations and the transport.
If you want to evolve the spec further then you need to weight the pro
and the cons of every suggestion carefully.
'Use id to signalize a notification'
Pro: No overhead
Con: Not clear for readers, uses inference. No possible
feedback on invalid calls (you cannot come with 'but I use [insert
name of framework] and it handles this for me). Notification cannot be
logged easily.
'Always use an id, use a flag to signalize a notification'
Pro: Enables feedback on invalid calls. Notifications can be
logged.
Con: A little overhead for most scenarios.
Anyone want to add to the list?
Sean
Max Kanat-Alexander
> Then the common ground might be "the client SHOULD provide an 'id' value
> IF it knows that the server will return the request results
> asynchronously or in other channel".
That sounds good.
> The point here is, if you are making an XHR then both server and client
> already know that your request's answer should in that very same session
> and unless you are making a batch request, using an id here is
> meaningless. Though if you are using or will use the new "WebSockets"
> API you still should provide an id which makes me think that the only
> use case of omitting the id seems this XHR thing and adding a relatively
> long name like "notification" just for this case not sounds plausible to me.
There could be lots of scenarios, though. I think that when designing a
protocol like this, it's definitely important to have reference
implementations and an idea of what the real-world applications would
be, but it's also important not to design it explicitly for a list of
valid situations, because there's always going to be situations you
can't predict. (See also:
http://www.codesimplicity.com/post/designing-too-far-into-the-future/ )
So, instead, it's best to design it to be as flexible as reasonably
possible. Making "notification" an explicit element leaves much more
flexibility in the protocol than re-using the "id" field for that purpose.
I think that a shorter name than "notification" would be good, though,
if anybody has some ideas.
Josh Marshall
Josh Marshall
Max Kanat-Alexander
> Rather obvious idea: 'notify': true, or 'notify': 0 / 1 if we're just
> going for 'truish' statements and /really/ want to minimize size.
I thought about that, too, but that effectively makes the "notify"
field mandatory if you want a reply, which adds an extra unnecessary
item in every call and also would break backwards-compatibility with 2.0.
Josh Marshall
Josh Marshall
Omi
A notification is similar to a call to:
void myFunction(....)
while a normal call is similar to a method call expecting a result.
To allow the client to understand which request response it is
receiving, the "id" field exists. For example in the TCP/IP scenario
where the server supports asynchronous responses, the other of the
responses might be different from the other of the requests. In the
HTTP transport scenario, it might not be of much use especially if
each connection waits for its response rather than piling all of the
responses onto a stack. I've noticed that so far in my use of JSON RPC
2.0, I've not needed to use the id field (on either the client or
server) but I've kept with it partly to maintain compliance and partly
to make sure it doesn't become a boulder smacking me in the face when
it becomes needed.
> > .
Max Kanat-Alexander
> I was thinking 'notify':true means it's a notification, and no response
> is necessary from the server,
Ahhh, okay. Yeah, I misunderstood and thought that "notify: true" meant
"send me a response". :-)
> but maybe that's unintuitive because it is a verb.
Yeah, there might be some better term to use....
Matt (MPCM)
This list seems to have exploded with lots of discussion all of a
sudden, which is exciting. But a lot of the discussion had immediately
jumped into what changes should be brought to a implied future 2.1
version without much discussion of if the changes make sense.
The way we have dealt with proposed changes in the past is to have
them defined in an extension specification (json-rpc+mycustom_blah).
The goal is to keep the core spec very simple. Even to the extent that
we do not directly even address transport issues.
Changes to the spec are a long process by intension, usually after
being defined via an extension specification. The managers of this
group usually take an informal vote as we propose changes, and have a
chance to be vocal over time about the proposed changes. Getting to
2.0 took a long time to keep it simple and extract a lot of implied
meaning that appeared in a 1.1 version. Prior to google groups we were
on yahoo groups, some of us for quite a few years dealing with these
concepts at this point. Lots of us rely on this is production
environments day in and day out.
So, with all that said... discussions about what belongs in the next
version of the specification are probably premature. Discussion about
extension specs which may be moved into a future version are not
however. Well discussed and defined specifications about anything that
can be leveraged by json-rpc (and other specs) are beneficial to all.
Using json-schema as a SMD mechanism is a good example.
I'm at home tonight, so I'll try and catch up and post some specific
points about some of the recent posts. The recent interest is very
exciting, just stick around for the discussions and be prepared to
justify your thoughts and approaches, and please keep the thoughts
separate from the core spec, as one or more people are likely to
always object to direct changes to the spec, but extension spec gives
room to prove your points while letting people use and try out the
concepts immediately.
--
Matt (MPCM)
Matt (MPCM)
back. The lack there of signifies the client not needing a response
object. Changing this should not be done lightly and without really
good reason. This is about the client stating its intentions.
A client can not reply on one request object per transport instance as
a fact. The client could easily be sending request objects that
outlive the immediate transport instance and thus that scope
separation might not out survive your request objects existence. Ajax-
type one-off requests make this hard to see, but the id is vital to
the client sorting out its many messages. It has little to do with the
server, and probably never should.
--
Matt (MPCM)
Burak Yiğit KAYA
Ajax-
type one-off requests make this hard to see, but the id is vital to
the client sorting out its many messages.
Max Kanat-Alexander
> the id is vital to the client sorting out its many messages.
True in some situations, but not in all situations.
> It has little to do with the server, and probably never should.
Okay. In that case, the protocol should also account for servers that
don't need it. I can tell you that thus far in all of the situations in
which I have used JSON-RPC, I have never needed the "id" field in a
conceptual or factual way.
Lorenzo Pastrana
Hi Matt,
I just stumbled over the questioning explosion of this WE ... thanks for the cooling ;D
On Sun, 2010-09-05 at 18:27 -0700, Matt (MPCM) wrote:
id's are required to signify the need for a response object being sent back. The lack there of signifies the client not needing a response object. Changing this should not be done lightly and without really good reason. This is about the client stating its intentions.
Given the current "full call" / notification mechanism, I'd like anyone trying to question that point to answer this question :
[question]
Why would someone needing a response to a call would ever fire a notification in the first place ?
[/question]
This is just plain misconception of the actual pattern.
If you need a response, ack, or logging, whatever ... well provide an ID and forget about notifications, that's as simple as that, even if your call could be interpreted as a simple "bang". I could rephrase : providing an ID is not a big deal as everybody seems to agree, so just do it if you do need feedback.
(As there seem to be lots of new posters / listeners I'd like to re-state that as usual my intention is not being harsh despite some people could think so)
Cheers,
Lo.
Max Kanat-Alexander
> providing an ID is not a big deal as everybody seems to agree, so just
> do it if you do need feedback.
It's a very significant and unnecessary complexity in an HTTP GET
situation. Generally, imagine telling people that your API looks like this:
rpc?method=Hello.world&jsonrpc=2.0&id=1
versus telling people that your API looks like this:
rpc?method=Hello.world
In fact, #2 can be implemented as a simple REST call, like:
rpc/Hello/world
Whereas #1 cannot be (without significant additional and unnecessary
complexity).
This is just one example.
Lorenzo Pastrana
> providing an ID is not a big deal as everybody seems to agree, so just > do it if you do need feedback. It's a very significant and unnecessary complexity in an HTTP GET situation.
Nothing related to one parameter or another then, HTTP GET won't support much more than hello world situations without "very significant and unnecessary complexity", for obvious reasons, the number one being "Where is JASON ?" :P
The "very significant and unnecessary complexity" is actually using HTTP GET for RPC ! Please use POST for any RPCs more complex than hello worlds :
Staying in HTTP domain, let's talk about a rather elementary json-rpc call
{
"jsonrpc": "2.0",
"method": "products.getinfo",
"params": [
123,
234,
345,
456,
567
],
"id": 987654321
}
Feed it to any endpoint : Content-Type: application/json-rpc Content-Length: ... paste the json blob and ... VOILA !Try doing the same by GET :
3.5.1 Encoded Parameters
Encoding Steps:
1. Base 64 param value
2. URL Encoded Base 64 param value
Pre-Encoded Params:
http://endpoint?jsonrpc=2.0&method=products.getinfo¶ms=[123,234,345,456,567]&id=987654321
Encoded Request:
http://endpoint?jsonrpc=2.0&method=products.getinfo¶ms=WzEyMywyMzQsMzQ1LDQ1Niw1Njdd&id=987654321
See http://groups.google.com/group/json-rpc/web/json-rpc-over-http for more ... I'd like these specs explicitely and strongly discourages the use of GET endpoints (but that's another topic)
Shouldn't we refocus on properly partitioned matters ?
1 - json rpc - cristal clear, rock solid, transport agnostic core
let's not forget the 2 main concerns :
a) JSON
b) RPC
2 - transport dependent considerations
3 - extensions
My 2.5 cents.
Lo.
Yitzchak Scott-Thoennes
> back. The lack there of signifies the client not needing a response
> object. Changing this should not be done lightly and without really
> good reason. This is about the client stating its intentions.
The fundamental "code smell" here is that id has two distinct purposes:
1) the id to pass back in the response, to be available to the client
to associate responses with requests.
2) indicates a non-notification by being present
Any time you dual-purpose a field this way, you are likely to end up
with boundary conditions where the dual-purposing doesn't make sense.
I believe this is the underlying reason people are getting so het up
over this seemingly trivial detail.
A far more sensible arrangement would be a separate "notification"
parameter (defaulting to false if not present).
This would then allow "id" to be optional, and to be omitted when the
client doesn't need it.
I'd be happy to write this up as an extension to the spec, but I'm
not really sure whether such a rule change would actually be welcome
to those writing json-rpc libraries without an actual version bump
to json-rpc itself.
Max Kanat-Alexander
> Ah, http ?... mmmh, GET !?
Yeah. Did you read the part at the bottom where I said that it was only
one example?
> 1. Base 64 param value
That's unnecessary and I've discussed how unnecessary it is in another
thread, and we all seemed to agree.
In response to the rest of your post, and as a completely unrelated
side note to this thread, HTTP GET support is very useful and
considerably simplifies things for many consumers. It's also an
excellent foundation to build a REST-based JSON-RPC service on.
Robert Goldman
> On 09/04/2010 07:52 AM, Derrell Lipman wrote:
>> An id allows the responses to multiple async requests to be
>> associated with their request when the response is received. If no id is
>> sent with a request that requires a response, only one could be sent at
>> a time or there would be no way to correlate the responses to their
>> requests.
>
> That's true, but:
>
> (a) I've never needed the id. For example, I'm often using the YUI
> DataSource module, which keeps track of requests separately. In fact,
> any good async framework keeps track of requests and responses in some
> way of its own.
Can you clarify this? It doesn't agree with my understanding. My
understanding is that JSON-RPC /is/ the async framework, and the id /is/
the way it keeps track of requests and responses.
I have worked on both a Common Lisp JSON-RPC library and a
Firefox-specific one, run over sockets. Both use the id field to manage
the response and request tracking, and neither has any alternative means
of tracking them.
The whole beauty of JSON-RPC, from my POV, is that it provides a dead
simple asynchrony framework, and the way it does it is by using the id
as its mechanism for tracking.
I would not like to see this made optional for requests that require
responses.
best,
r
Max Kanat-Alexander
> Can you clarify this? It doesn't agree with my understanding. My
> understanding is that JSON-RPC /is/ the async framework, and the id /is/
> the way it keeps track of requests and responses.
JSON-RPC is a protocol, not a transport. Many transports have a method
of associating requests with responses on their own.
I personally have never needed to use the "id" field, and my
implementations will return responses whether you specify an "id" field
or not, at least partially in the spirit of "be liberal in what you accept".
> I would not like to see this made optional for requests that require
> responses.
Why do you require an id field for requests that require responses in
your implementation? Why would the "notification: true" system not work
for you?
Josh Marshall
>
> I personally have never needed to use the "id" field, and my
> implementations will return responses whether you specify an "id" field
> or not, at least partially in the spirit of "be liberal in what you accept".
>
I'm assuming you aren't talking about batch requests here. Based on
the spec, it is completely permissible to request:
[
{"jsonrpc": "2.0", "method": "sum", "params": [2,4], "id": "1"},
{"jsonrpc": "2.0", "method": "email", "params": ['subject',
'message'], "id": "2"},
{"jsonrpc": "2.0", "method": "random", "id": "3"}
]
and receive:
[
{"jsonrpc": "2.0", "result": true, "id": "2"},
{"jsonrpc": "2.0", "result": 6, "id": "1"},
{"jsonrpc": "2.0", "result": 0.3577654, "id": "3"}
]
Without ids, that would look like:
[
{"jsonrpc": "2.0", "result": true},
{"jsonrpc": "2.0", "result": 6},
{"jsonrpc": "2.0", "result": 0.3577654}
]
I'm not sure how you would implement that without ids. (But I might be
missing something.) Now, obviously for a single request -> single
response in a shared-nothing environment, ids are not /as/ necessary,
but I still think they are intuitive and should be required for
optimum compatibility between implementations. Also, this keeps the
differences between single request and batch requests to a minimum,
which just makes the spec that much easier for people to pick up.
That's just my interpretation of the conversation, so apologies if
I've overlooked something.
Now notifications, those are a different argument (although there is
potentially impact on the id absence / requirement question.)
Josh Marshall
Max Kanat-Alexander
> I'm assuming you aren't talking about batch requests here.
I'm not. I'm talking about single requests.
> I'm not sure how you would implement that without ids.
I agree--if you're going to do batch requests, you should probably add
ids, although I think that that should be up to the implementor--a
"SHOULD", not a "MUST".
Matt (MPCM)
wrote:
> > id's are required to signify the need for a response object being sent
> > back. The lack there of signifies the client not needing a response
> > object. Changing this should not be done lightly and without really
> > good reason. This is about the client stating its intentions.
>
> The fundamental "code smell" here is that id has two distinct purposes:
>
> 1) the id to pass back in the response, to be available to the client
> to associate responses with requests.
>
> 2) indicates a non-notification by being present
>
> Any time you dual-purpose a field this way, you are likely to end up
> with boundary conditions where the dual-purposing doesn't make sense.
> I believe this is the underlying reason people are getting so het up
> over this seemingly trivial detail.
json-rpc since the beginning and it comes from a different point of
view. If you assume that by default the client is passing messages,
not calling functions, you do not need a response to be returned.
Adding an `id` field changes the meaning from `message` to a `call`,
telling the server that the client wants a response. In this view an
id is not a dual purposed concept, but a straightforward addition of a
new field for a different behavior from the server.
> A far more sensible arrangement would be a separate "notification"
> parameter (defaulting to false if not present).
request object to the transport instance life time and suggesting
optimizations based on that view. json-rpc is used in places where
that is not true and there is little gained from the "optimization".
> This would then allow "id" to be optional, and to be omitted when the
> client doesn't need it.
field is different.
> I'd be happy to write this up as an extension to the spec, but I'm
> not really sure whether such a rule change would actually be welcome
> to those writing json-rpc libraries without an actual version bump
> to json-rpc itself.
drastically changes the meaning of the request object based on
contents and adds very little with the change, short of changing the
meaning. I would imagine extensions with those sorts of
characteristics are not likely to see much support/adoption by the
community. We all want a simpler time of things, which is what draws
many to json-rpc.
--
Matt (MPCM)
Yitzchak Scott-Thoennes
> On 09/06/2010 03:05 PM, Josh Marshall wrote:
> > I'm assuming you aren't talking about batch requests here.
>
> I'm not. I'm talking about single requests.
>
> > I'm not sure how you would implement that without ids.
>
> I agree--if you're going to do batch requests, you should probably add
> ids, although I think that that should be up to the implementor--a
> "SHOULD", not a "MUST".
Not even a SHOULD, IMO.
In some cases, the actual data returned will be self-identificatory.
For instance, batch fetching a bunch of objects by ids, where those
ids found are returned as part of the object.
People are saying omitting the id reflects a transport bias that
doesn't belong in the spec; I see it the other way around;
requiring an "id":1 in so many cases where it is just plain
silly reflects a bias towards asynchronous socket transport.
Yes, we need to support id for many cases, but mandating it
in all cases to be "transport-neutral" isn't transport
neutral at all; it's support for one form of transport that
doesn't belong in the spec.
Yitzchak Scott-Thoennes
> On Sep 6, 1:08 pm, Yitzchak Scott-Thoennes wrote:
> > The fundamental "code smell" here is that id has two distinct purposes:
> >
> > 1) the id to pass back in the response, to be available to the client
> > to associate responses with requests.
> >
> > 2) indicates a non-notification by being present
> >
> > Any time you dual-purpose a field this way, you are likely to end up
> > with boundary conditions where the dual-purposing doesn't make sense.
> > I believe this is the underlying reason people are getting so het up
> > over this seemingly trivial detail.
>
> I can see where the thought comes from. But this has been a concept in
> json-rpc since the beginning and it comes from a different point of
> view. If you assume that by default the client is passing messages,
> not calling functions, you do not need a response to be returned.
> Adding an `id` field changes the meaning from `message` to a `call`,
> telling the server that the client wants a response. In this view an
> id is not a dual purposed concept, but a straightforward addition of a
> new field for a different behavior from the server.
I read that paragraph and see it justifying one of the two purposes, not
explaining how they are really just one purpose. And I wasn't
questioning the need for both messages and calls.
> > A far more sensible arrangement would be a separate "notification"
> > parameter (defaulting to false if not present).
>
> I'm not sure it is, see the comment above. You keep linking the
> request object to the transport instance life time and suggesting
> optimizations based on that view. json-rpc is used in places where
> that is not true and there is little gained from the "optimization".
I think you are thinking of someone else. I'm not thinking of
optimization at all, just of making the spec fall more in line
with expectations of how people *will* use it.
> > This would then allow "id" to be optional, and to be omitted when the
> > client doesn't need it.
>
> The id *IS* optional, but the meaning implied by the absence of the
> field is different.
Yes, you either have to supply a (possibly meaningless to the client) id
or have it be treated as a notification, because the id field means both
"not a notification" and "the client needs this id returned" instead of
decoupling the two purposes into two fields.
> > I'd be happy to write this up as an extension to the spec, but I'm
> > not really sure whether such a rule change would actually be welcome
> > to those writing json-rpc libraries without an actual version bump
> > to json-rpc itself.
>
> You are welcome to write it up as an extension specification, but it
> drastically changes the meaning of the request object based on
> contents and adds very little with the change, short of changing the
> meaning. I would imagine extensions with those sorts of
> characteristics are not likely to see much support/adoption by the
> community. We all want a simpler time of things, which is what draws
> many to json-rpc.
Agreed. But if you require spec changes to be vetted via an extension
first, you very much restrict the kind of spec changes that can be
proposed.
Alexandre Morgaut
REST is resource oriented and expect that each resource a server can provide must be accessible through a URI
HTTP is meant to help building architecture with a REST style
what would be important with the support of the GET method by JSON-RPC is to respect the GET safety property
When doing a GET request on a server, no data should be modified on the server (only the log files ;-) )
Of course, as JSON RPC specify a representation format, the values of the jsonrpc parameter may be set in HTTP headers
ex:
Accept: application/rpc+json;version=2
(ok I'm pushing the MIME type I'd like to use...)
But I think it's ok to be able to fix it directly in the query string, as we already are used put a file extension in the URI
About the id, I agree I'd prefer be able to drop it to allow the cache
ex:
/rpc?$method=turnover&year=2009&month=12
Yes, you can see I experimented also other URI formats
I also agree params doesn't need base64 encoding by default
Alexandre Morgaut
REST is resource oriented and expect that each resource a server can provide must be accessible through a URI
HTTP is meant to help building architecture with a REST style
what would be important with the support of the GET method by JSON-RPC is to respect the GET safety property
When doing a GET request on a server, no data should be modified on the server (only the log files ;-) )
Of course, as JSON RPC specify a representation format, the values of the jsonrpc parameter may be set in HTTP headers
ex:
Accept: application/rpc+json;version=2
(ok I'm pushing the MIME type I'd like to use...)
But I think it's ok to be able to fix it directly in the query string, as we already are used put a file extension in the URI
About the id, I agree I'd prefer be able to drop it to allow the cache
ex:
/rpc?$method=turnover&year=2009&month=12
Yes, you can see I experimented also other URI formats
I also agree params doesn't need base64 encoding by default
On Sep 6, 2010, at 12:45 PM, Max Kanat-Alexander wrote:
Luis Montes
--
You received this message because you are subscribed to the Google Groups "JSON-RPC" group.
To post to this group, send email to json...@googlegroups.com.
To unsubscribe from this group, send email to json-rpc+u...@googlegroups.com.
Gaetano Giunta
> On 09/06/2010 02:23 PM, Robert Goldman wrote:
>> Can you clarify this? It doesn't agree with my understanding. My
>> understanding is that JSON-RPC /is/ the async framework, and the id /is/
>> the way it keeps track of requests and responses.
> JSON-RPC is a protocol, not a transport. Many transports have a method
> of associating requests with responses on their own.
>
> I personally have never needed to use the "id" field, and my
> implementations will return responses whether you specify an "id" field
> or not, at least partially in the spirit of "be liberal in what you accept".
I always have had a little trouble in uderstanding why a client should be allowed to specify in its call whether he wants an answer back or not. Is it not the
server/the function being called that determines the "message passing" vs. "function call" pattern?
- if the function being called has no meaningful return value, adding an id in the call merely forces the server to add a useless NULL response
- if the function being called has a return value, why would the client be able not want it?
A little off-topic: a question to implementors of http-based libraries: how do you implement management of the id field? Is it the duty of the user of the API
to provide an id, or does the library add an automatically generated one under the hood?
bye
Gaetano
Lorenzo Pastrana
Yes, you either have to supply a (possibly meaningless to the client) id or have it be treated as a notification,
because the id field means both "not a notification" and "the client needs this id returned" instead of decoupling the two purposes into two fields.
the unique meaning of the ID field is whether the client is listening or not for a response.
- ID : "I'm listening on ID slot"
- no ID : "I'm not listening"
There is actually no need to decouple this bit because both behaviors are mutually exclusive,
Then doubling the field would induce error prone ambiguities :
If a message has to carry the two slots, the case of :
notification:false
is not self sufficient, the server needs to refer to an ID for talk-back, if no ID is provided then the call must be assumed "not to be in a batch" AND hazardous assumptions are to be made on the synchronicity of the transport OR the call being just plain wrong ...
In other words : a can of worms.
As said previously the ID is needed in batches and provides the simplest pivotal point for any transport to be (possibly) asynchronous.
Agreed. But if you require spec changes to be vetted via an extension first, you very much restrict the kind of spec changes that can be proposed.
The current spec has almost four years maturation, it's status is currently "about to be ratified" for there is about nothing to be removed without breaking what's working, every word of it has been discussed, weighted and agreed on a very long period.
Lo.
Burak Yiğit KAYA
The current spec has almost four years maturation, it's status is currently "about to be ratified" for there is about nothing to be removed without breaking what's working, every word of it has been discussed, weighted and agreed on a very long period.
Lorenzo Pastrana
I believe it should be strongly discouraged because there's so little left of JSON-RPC in GET requests, and the translation effort on server side is such that I couldn't call it JSON-RPC anymore ...
I consider JSON-RPC + GET a brutal hack over a nice protocol ;P
Which is not the case in the JSON-RPC + POST pattern that stays a clean and appropriate transport layer.
This is just my opinon, as I'm almost not involved in the spec.
BTW on cross-domain :
With the emergence and adoption of HTML5 and especially XMLHttpRequest Level 2, cross domain might not be a client issue for long :
http://www.w3.org/TR/XMLHttpRequest2/#cross-origin-request
https://developer.mozilla.org/en/http_access_control
Lo.
Lorenzo Pastrana
On Tue, Sep 7, 2010 at 14:31, Lorenzo Pastrana <past...@ultraflat.net> wrote:
The current spec has almost four years maturation, it's status is currently "about to be ratified" for there is about nothing to be removed without breaking what's working, every word of it has been discussed, weighted and agreed on a very long period.
Isn't this is a little bit like "we have already talked about these and whatever you say, we will not change it"?
Elaborating a protocol is a delicate exercise.
It requires a particular mind frame, in our case it means trying to consider various use cases while avoiding bloat, be future ready while avoiding over engineering, be production ready while putting most implementation and transport considerations aside ...
That's not easy to keep a collective effort focused on nitty-gritties while promoting a clear and global view over the full picture, and most of all : it takes time, believe me.
There has been lots of activity bursts like this one in the elaboration of the specs and even some tense moments, but Matt could tell you : nothing has never been written down the document until the temperature has cooled, and an agreement was reached.
JSON-RPC is forcing an asynchronous transport where as IMO it should be transport neutral.
In the "protocol mind frame" the ID field just allows any transport to carry asynchronous calls AND batches.
Lo.
Luis Montes
I agree that the spec you linked to is hackish, but making RPC requests on a URL doesn't have to be :)
4000 chars in a URL is plenty for the type of requests that I've been doing JSON-RPC, and just serializing the entire RPC object to a single request parameter makes it easy to toggle between GET and POST.
Dave Wright
> server/the function being called that determines the "message passing" vs. "function call" pattern?
> - if the function being called has no meaningful return value, adding an id in the call merely forces the server to add a useless NULL response
verify that the server received and processed the request. In some
transports like HTTP this may be duplicative of the HTTP response
which comes anyway, but in most other transports it is not.
> - if the function being called has a return value, why would the client be able not want it?
"optional" return value, one that all clients don't need.
While I see your point about having the notifications vs. function
call paradigm be controlled by the server (and defined for each
function), from an ease of implementation perspective I think having
it on the client makes sense as well and has less of a chance of
error. After all, the client is ultimately the one that consumes (or
doesn't consume) the response. No need for a server to deliver
something the client doesn't want.
As to the bigger question of whether notification behavior should be
indicated by the "id" field or a separate "notify" field, personally I
don't have a strong preference.
I agree with Yitzchak's point that it gives the id field a "double
meaning", but I don't really see how that causes any issues. If you
aren't going to use the id field to match responses.. fine, just pass
"id=1" to every request. It's more compact that "notify=true"
anyway :)
This isn't something that I see as worth changing the specification
over. No one has given a strong argument for why using the id field to
indicate a response is desired limits functionality in any way on the
client or the server. It may be "prettier" to have a separate
notification field, but compact and simple work for me.
Burak Yiğit KAYA
There has been lots of activity bursts like this one in the elaboration of the specs and even some tense moments, but Matt could tell you : nothing has never been written down the document until the temperature has cooled, and an agreement was reached.
JSON-RPC is forcing an asynchronous transport where as IMO it should be transport neutral.JSON-RPC is forcing nothing on the transport, waiting for the server's response is perfectly OK if that's what you want/need, nothing prevents it in the current spec.
In the "protocol mind frame" the ID field just allows any transport to carry asynchronous calls AND batches.
Yitzchak Scott-Thoennes
> As to the bigger question of whether notification behavior should be
> indicated by the "id" field or a separate "notify" field, personally I
> don't have a strong preference.
"notification", please. "notify" is much more subject to being taken
exactly the wrong way.
> I agree with Yitzchak's point that it gives the id field a "double
> meaning", but I don't really see how that causes any issues. If you
> aren't going to use the id field to match responses.. fine, just pass
> "id=1" to every request. It's more compact that "notify=true"
> anyway :)
There are no implementation issues. The issues are social. By the spec
not allowing a client to specify "I want a response but don't need an
id", many people new to the spec will come here and ask why...or just
conclude that notifications are some poorly conceived bolted on thing
and just not support them...as the google poster has apparently done.
> This isn't something that I see as worth changing the specification
> over. No one has given a strong argument for why using the id field to
> indicate a response is desired limits functionality in any way on the
> client or the server. It may be "prettier" to have a separate
> notification field, but compact and simple work for me.
Certainly the 2.0 spec should not be changed. I, at least, am only
hoping to lay the groundwork for support for a change in a future
version.
Yitzchak Scott-Thoennes
>
> the unique meaning of the ID field is whether the client is listening
> or not for a response.
>
> - ID : "I'm listening on ID slot"
> - no ID : "I'm not listening"
slot is a transport-specific need (and even then, or in batch, is not
always needed). And that seems to cause some to not even conceive of
the obvious third case (and hence not see any dual-purpose).
> notification:false
>
> is not self sufficient, the server needs to refer to an ID for
> talk-back, if no ID is provided then the call must be assumed "not to
> be in a batch" AND hazardous assumptions are to be made on the
> synchronicity of the transport OR the call being just plain wrong ...
>
> In other words : a can of worms.
>
> As said previously the ID is needed in batches and provides the
> simplest pivotal point for any transport to be (possibly)
> asynchronous.
"needs", "needed": This is not true, or this discussion would never have
arisen.
Robert Goldman
> On 09/06/2010 02:23 PM, Robert Goldman wrote:
>> Can you clarify this? It doesn't agree with my understanding. My
>> understanding is that JSON-RPC /is/ the async framework, and the id /is/
>> the way it keeps track of requests and responses.
>
> JSON-RPC is a protocol, not a transport. Many transports have a method
> of associating requests with responses on their own.
>
> I personally have never needed to use the "id" field, and my
> implementations will return responses whether you specify an "id" field
> or not, at least partially in the spirit of "be liberal in what you accept".
>
>> I would not like to see this made optional for requests that require
>> responses.
>
> Why do you require an id field for requests that require responses in
> your implementation? Why would the "notification: true" system not work
> for you?
Both of the JSON-RPC libraries on which I have worked operate as follows:
Client issues request, and caches information about the call in a table
(hash table, vector, JS object, what-have-you).
Client thread (or, in JS, an event handler) waits for response from
server. When a response arrives, the client library looks up the
JSON-RPC call in the table, using the id field in the response, and
issues it to the calling code.
The design of JSON-RPC seems clearly to assume (or at the very least
permit) such a client implementation, which will fail if id's are not
present.
FWIW, I think it's incumbent on you, as the person who wants to change
the existing spec, to explain to us why this is UNnecessary, instead of
asking us to demonstrate that it is necessary....
best,
r
Robert Goldman
> On Mon, 2010-09-06 at 15:35 -0700, Max Kanat-Alexander wrote:
>> On 09/06/2010 03:05 PM, Josh Marshall wrote:
>>> I'm assuming you aren't talking about batch requests here.
>>
>> I'm not. I'm talking about single requests.
>>
>>> I'm not sure how you would implement that without ids.
>>
>> I agree--if you're going to do batch requests, you should probably add
>> ids, although I think that that should be up to the implementor--a
>> "SHOULD", not a "MUST".
>
> Not even a SHOULD, IMO.
>
> In some cases, the actual data returned will be self-identificatory.
> For instance, batch fetching a bunch of objects by ids, where those
> ids found are returned as part of the object.
I believe that the above reflects a misunderstanding of the function of
the id field. The id field is /not/ the identifier of some object or
other on the server. It is the identifier /of the request itself/. So
the above example really doesn't make sense. The id is part of the
JSON-RPC protocol itself; it is not visible to the server for other use
(e.g., to find an object).
Robert Goldman
> On Mon, 2010-09-06 at 16:15 -0700, Matt (MPCM) wrote:
>> On Sep 6, 1:08 pm, Yitzchak Scott-Thoennes wrote:
>>> This would then allow "id" to be optional, and to be omitted when the
>>> client doesn't need it.
>>
>> The id *IS* optional, but the meaning implied by the absence of the
>> field is different.
>
> Yes, you either have to supply a (possibly meaningless to the client) id
> or have it be treated as a notification, because the id field means both
> "not a notification" and "the client needs this id returned" instead of
> decoupling the two purposes into two fields.
I don't think the above is coherent. The id CANNOT be meaningless to
the client --- the client has, itself, provided the id. Indeed, it
doesn't seem to make sense to say that the server "supplies" the id.
The id is supplied by the client, and must simply make the round trip
through the server.
Dennis
the bandwith usage, (small), or doesn't need the complexity of the
feature, then it may be avoided by not using it.
OTOH, most handheld devices, a BIG market for JSON services, are using
multiple requests to JSON sources while (sometimes) multitasking
between other,local, functionality. They NEED to be able to keep track
of responses to any request.
And whether or not to get a response? Much of the problem with
software is the handling of responses. They help determine the next
state, or their absence or timeout should do so.
A broadcast notification would be an obvious exception.
On Sep 6, 12:47 am, Lorenzo Pastrana <pastr...@ultraflat.net> wrote:
> Hi Matt,
>
> I just stumbled over the questioning explosion of this WE ... thanks for
> the cooling ;D
> On Sun, 2010-09-05 at 18:27 -0700, Matt (MPCM) wrote:
> > id's are required to signify the need for a response object being sent
> > back. The lack there of signifies the client not needing a response
> > object. Changing this should not be done lightly and without really
> > good reason. This is about the client stating its intentions.
>
> seemed to answer instead of speculating on notification mechanism ...
>
> Given the current "full call" / notification mechanism, I'd like anyone
> trying to question that point to answer this question :
>
> [question]
> Why would someone needing a response to a call would ever fire a
> notification in the first place ?
> [/question]
>
> This is just plain misconception of the actual pattern.
>
> If you need a response, ack, or logging, whatever ... well provide an ID
> and forget about notifications, that's as simple as that, even if your
> call could be interpreted as a simple "bang". I could rephrase :
> do it if you do need feedback.
>
> re-state that as usual my intention is not being harsh despite some
> people could think so)
>
> Cheers,
> Lo.
Yitzchak Scott-Thoennes
No, I have no misunderstanding. I was indeed talking about an id
supplied by the client but meaningless to the client, and, separately,
object ids supplied in the params of batched requests and returned in
the responses which obviate the need for the client to use the json-rpc
request id.
Shame it was called "id", not "request_id" or some such, but it's no
doubt too late to fight that fight (and the additional capitalization/
camel case/underscore battle).
Louis Ryan
This change looks the most "hard" to implement in generic jsonrpc clients (or the more specific one).Louis Ryan wrote:Folks,
As announced at Google I/O were working on launching JSON-RPC support for most of our newer APIs. We've had success with using JSON-RPC for the client with OpenSocial so we are broadening our support for it. In particular JSON-RPC has proven useful as a dispatch mechanism for it's very obvious batch support and naming and parsing conventions that work well in Javascript clients. This by no means indicates that we are abandoning RESTful APIs or that we design first as RPC, quite the opposite in fact. It's simply that for newer APIs we support there is no reason to limit ourselves and our clients to a single transport mechanism for all use cases.
There are a few areas where we are just non-compliant and have some questions about the value of what the spec is requiring. Let me know what you think as we'd like to launch fairly soon and we're very interested in the communities feedback.
CheersLouisJSON-RPC version
The specification sections 4 & 5 mandates that the value
“jsonrpc” : “2.0”
be provided at the top-level of every request and response. In our case all our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so while we’re happy to accept it on input, and even reject requests that specify a value other than “2.0” we don't reject requests that omit this value and we do not populate it in the output.
Absence of ‘id’ to indicate that no response should be produced
The specification section 4 defines any request that does not contain an ‘id’ to be a ‘notification’. A notification is a request the response to which the caller does not care about and so the system should not produce a response object. In the case of a batch of requests this would mean that the cardinality of the batch response may not necessarily match that of the request. Our current behavior is to always produce a response even if an id is omitted primarily because even if something is dispatching an asynchronous job there is still the need for parameter validation which should be confirmed to the caller. Does anyone make significant use of the behavior described in the spec of perceive any performance advantage from it?
Error code alignment
We produce codes per the specification for:
-32700 - Invalid JSON
-32600 - Invalid request object
however we vary from the spec by default for the following codes:
-32601 - Method not found. Instead we use the HTTP code 404 NOT FOUND
-32602 - Invalid parameters. Instead we use the HTTP code 400 BAD REQUEST
-32603 - Internal error. Instead we use the HTTP code 500 INTERNAL SERVER ERROR for failures in the Apiary stack and the spec code for failures caused by backend errors.
This variance is maintained primarily for compatibility with the OpenSocial JSON-RPC implementation in Apache Shindig which followed the same pattern. I think the error codification in the spec is one of its weaker areas about which there is good discussion on one of the other threads here. We use the 'data' field inside an error response to carry an array of more detailed error objects as our system allows for APIs to report secondary errors.
- location and name of invalid parameters- textual namespaced error codes (see the other thread for discussion)- debug information and identifiers for request tracing- help links to reference documentation if requested
apiVersion:
The specification doesn’t provide a mechanism for describing different versions on the same API. We added support for this by defining an ‘apiVersion’ field at the top level of the request which contains a string literal of the version name. E.g
{
id : ‘12345’,
method : “language.diacritize.get”,
apiVersion : ‘v2’
...
}
Could you not simply put that field as 1st (or last) element in the name of the functions themselves, eg: language.diacritize.get.v2 ?
We looked into this but felt a separate field was a cleaner solution. I wouldnt put the version at the end as it make language bindings for the verb look odd, e.g. in Javascript language.diacritize.get.v2(<params>) vs. language.diacritize.v2.get(<params>) which looks more natural. The issue with putting the version earlier in the name is that the placement will look a bit inconsistent. We have to deal with the fact that there are families of APIs which wi be at different versions so we can't push the version number up the naming hierarchy. E.g
language.translate.v2.get & language.diacritize.v3.get cannot be transformed sensibly into language.v2...
We do not currently echo back the apiVersion in the response and it’s worth discussing whether we should do so particularly when no apiVersion is specified in the request and the server chooses one by default.
--
You received this message because you are subscribed to the Google Groups "JSON-RPC" group.
To post to this group, send email to json...@googlegroups.com.
To unsubscribe from this group, send email to json-rpc+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/json-rpc?hl=en.
Louis Ryan
On Thu, 2010-09-02 at 20:19 -0700, Louis Ryan wrote:
Folks,
As announced at Google I/O were working on launching JSON-RPC support for most of our newer APIs.
Hi Louis, first of all that's great news :D
There are a few areas where we are just non-compliant and have some questions about the value of what the spec is requiring. Let me know what you think as we'd like to launch fairly soon and we're very interested in the communities feedback.
JSON-RPC version
The specification sections 4 & 5 mandates that the value
“jsonrpc” : “2.0”
be provided at the top-level of every request and response. In our case all our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so while we’re happy to accept it on input, and even reject requests that specify a value other than “2.0” we don't reject requests that omit this value and we do not populate it in the output.
That could sound, well ... conservative in your own case, but obviously implies that 2.0 is your default dialect for now, however there are a couple of points to be signaled :
JSON-RPC 2.0 has (wery few but some) antecedents in 1.0 :
>From the specs, 3 - Compatibility :
JSON-RPC 2.0 does not work with JSON-RPC 1.0 clients or servers.
[snip]it is easy to distinguish between the two versions as 2.0 always has a member named "jsonrpc" with a String value of "2.0" whereas 1.0 does not[snip]
The term "Compatibility" in that paragraph is intended "backward" and that's the only place where it was addressed (in an implicit way thus). Fact is that "the future's not ours to see" ... and neglecting that could turn in an unforeseen bullet heading slowly toward your foot ...
The jsonrpc member requirement is mostly intended for future compatibility, and future compatibility has been a strong concern all along the specs elaboration. Chances are that you'll be blessing that 10 bytes spent someday.
I've seen compactness used as an argument for the notification mechanism to cause response suppression and it is certainly a valid argument. In situations where there is an additional contract between the client and the server that is ex-protocol I think these kinds of optimizations are valid for low-bandwidth scenarios. In our case were clearly stating that we will not support JSON-RPC 1.0 or anything before 2.0 which I think is a reasonable stance to take. I don't know to what extent other servers are relying on these value on input and output. In particular I'm curious about what dependencies people have on the output version. If the spec is requiring the value in the request and an id which is exactly correlateable to the produced response then what use is the version in the response? Is the expectation that I can make the call in 2.0 and get a response in 3.0 and if so to what end?
Absence of ‘id’ to indicate that no response should be produced
In the case of a batch of requests this would mean that the cardinality of the batch response may not necessarily match that of the request.
I'd consider the cardinality of a batch being actually N - number_of_notifications
This causes and incremental increase in the complexity of the clients when doing batch handling. Beware pathological clients that miss this subtlety of the spec and blow up with indexing issues.
Our current behavior is to always produce a response even if an id is omitted primarily because even if something is dispatching an asynchronous job there is still the need for parameter validation which should be confirmed to the caller.
If you do need any kind of validation / response, why do you omit the request ID in the first place ?
How an asynchronous client could ever dispatch a response without a request ID ?
When you issue a single request in XHR for instance you use the functional callback mechanism in JS to correlate the response with the call so the id is superfluous in this case. We can always have our client produce a synthetic one which has no meaning so it's not a big deal its just for the overwhelming majority of our expected traffic its not needed.
Does anyone make significant use of the behavior described in the spec of perceive any performance advantage from it?
The main purpose of this kind of feature, as said Henry, is 'state change' notification ... A simple example would be a MMORPG where the client would periodically notify the server about it's player direction and speed so the server can compute collisions, encounters and so on.
When the player takes an action that could fail the client would use a request ID and hope for a response.
I'm OK with the use case but the conflation of identity with the desire for response suppression is clearly worth discussion (as can be seen by this thread). I can live with the behavior as we would just have our client code always produce an id to get the behavior we want.
Error code alignment
See the thread running ...
apiVersion:
The specification doesn’t provide a mechanism for describing different versions on the same API.
Probably because JSON-RPC is a protocol, not an API :D
We added support for this by defining an ‘apiVersion’ field at the top level of the request which contains a string literal of the version name. E.g
{
id : ‘12345’,
method : “language.diacritize.get”,
apiVersion : ‘v2’
...
}
This sounds to me like an "encapsulation error" but for communications, as if rails where to know if the train carried cargo or people ...
Why not :
{
id : ‘12345’,
method : “v2.language.diacritize.get”,
...
}
Or just a specific entry point ?
v2.some.api.server.google.com/call
See my earlier comment for some context on this. There are some expectations that we need to meet that make this an interesting choice.
- People are used to version names with dots in them which makes them a poor choice for valid Javascript identifiers.
- We have more than one API under the same namespace with different versions which while not strictly a problem may cause user confusion
language.diacritize.v2.get
language.translate.v3.get
as we cant guarantee that the version if the first literal value in the identifier. This is something we may address by other means in our client so I'm not ruling this out.
{
id : ‘12345’,
method : “language.diacritize.get”,
...
}
Cheers,
Lorenzo
Gaetano Giunta
On Fri, Sep 3, 2010 at 6:56 AM, Lorenzo Pastrana <past...@ultraflat.net> wrote:
On Thu, 2010-09-02 at 20:19 -0700, Louis Ryan wrote:Hi Louis, first of all that's great news :D
Folks,
As announced at Google I/O were working on launching JSON-RPC support for most of our newer APIs.
There are a few areas where we are just non-compliant and have some questions about the value of what the spec is requiring. Let me know what you think as we'd like to launch fairly soon and we're very interested in the communities feedback.
JSON-RPC version
The specification sections 4 & 5 mandates that the value
�jsonrpc� : �2.0�
be provided at the top-level of every request and response. In our case all our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so while we�re happy to accept it on input, and even reject requests that specify a value other than �2.0� we don't reject requests that omit this value and we do not populate it in the output.
That could sound, well ... conservative in your own case, but obviously implies that 2.0 is your default dialect for now, however there are a couple of points to be signaled :
JSON-RPC 2.0 has (wery few but some) antecedents in 1.0 :
>From the specs, 3 - Compatibility :
JSON-RPC 2.0 does not work with JSON-RPC 1.0 clients or servers.
[snip]it is easy to distinguish between the two versions as 2.0 always has a member named "jsonrpc" with a String value of "2.0" whereas 1.0 does not[snip]
The term "Compatibility" in that paragraph is intended "backward" and that's the only place where it was addressed (in an implicit way thus). Fact is that "the future's not ours to see" ... and neglecting that could turn in an unforeseen bullet heading slowly toward your foot ...
The jsonrpc member requirement is mostly intended for future compatibility, and future compatibility has been a strong concern all along the specs elaboration. Chances are that you'll be blessing that 10 bytes spent someday.
I guess it is to avoid having a "version 1.0" server that is liberal in what it accepts responding to the version 2 client.
I've seen compactness used as an argument for the notification mechanism to cause response suppression and it is certainly a valid argument. In situations where there is an additional contract between the client and the server that is ex-protocol I think these kinds of optimizations are valid for low-bandwidth scenarios. In our case were clearly stating that we will not support JSON-RPC 1.0 or anything before 2.0 which I think is a reasonable stance to take.� I don't know to what extent other servers are relying on these value on input and output. In particular I'm curious about what dependencies people have on the output version. If the spec is requiring the value in the request and an id which is exactly correlateable to the produced response then what use is the version in the response? Is the expectation that I can make the call in 2.0 and get a response in 3.0 and if so to what end?
The client could, in theory, even properly parse both v1 and v2 responses, instead of rejecting v1 responses as invalid...
Max Kanat-Alexander
> Client thread (or, in JS, an event handler) waits for response from
> server. When a response arrives, the client library looks up the
> JSON-RPC call in the table, using the id field in the response, and
> issues it to the calling code.
Okay, that sounds like a reasonable implementation. So, the id could
still be optional in the protocol--you just need one. If the client
didn't provide one, you could generate one and use it internally in your
library, right?
> FWIW, I think it's incumbent on you, as the person who wants to change
> the existing spec, to explain to us why this is UNnecessary, instead of
> asking us to demonstrate that it is necessary....
I never said that the "id" field is unnecessary, I simply said that it
should be optional, and that its optional-ness shouldn't imply something
else.
For an example of a disastrous overloading of a field in another
domain, look at the "autocomplete" attribute on HTML input fields.
There are many use cases for JSON-RPC. The "notification: true" system
would work in all of those use cases. However, I have demonstrated
several cases in this thread and other threads where the "id" field is
itself not necessary or is an inconvenience.
Omi
call
e.g.
{ "jsonrpc": "2.0", "method": "myNamespace.myMethod", "params" :
{ "ver" : 2, ...}}
On Sep 7, 4:48 pm, Louis Ryan <lr...@google.com> wrote:
>
>
>
>
>
> > On Thu, 2010-09-02 at 20:19 -0700, Louis Ryan wrote:
>
> > Folks,
>
> > Hi Louis, first of all that's great news :D
>
> > There are a few areas where we are just non-compliant and have some
> > questions about the value of what the spec is requiring. Let me know what
> > you think as we'd like to launch fairly soon and we're very interested in
> > the communities feedback.
>
> > See the thread running ...
>
> > .
Robert Goldman
> what of placing the version with the parameters set to the function/
> call
> e.g.
> { "jsonrpc": "2.0", "method": "myNamespace.myMethod", "params" :
> { "ver" : 2, ...}}
>
I'd really rather not see that done. The version is meta-data, and it's
a matter for the JSON-RPC library to be dealing with. The parameters
are things that the library should just be throwing down the tube to
whatever implements the function call.
If there's going to be metadata, I'd rather it be "on" the "envelope"
rather than "in" the envelope, if you know what I mean.
best,
r
> On Sep 7, 4:48 pm, Louis Ryan <lr...@google.com> wrote:
>> On Fri, Sep 3, 2010 at 6:56 AM, Lorenzo Pastrana <pastr...@ultraflat.net>wrote:
>>
>>
>>
>>
>>
>>> On Thu, 2010-09-02 at 20:19 -0700, Louis Ryan wrote:
>>
>>> Folks,
>>
>>> As announced at Google I/O<http://code.google.com/events/io/2010/sessions/how-google-builds-apis...>were working on launching JSON-RPC support for most of our newer APIs.
>>
>>> Hi Louis, first of all that's great news :D
>>
>>> There are a few areas where we are just non-compliant and have some
>>> questions about the value of what the spec is requiring. Let me know what
>>> you think as we'd like to launch fairly soon and we're very interested in
>>> the communities feedback.
>>
>>> *JSON-RPC version* The specification sections 4 & 5 mandates that the
>>> value
>>> �jsonrpc� : �2.0�
>>> be provided at the top-level of every request and response. In our case all
>>> our APIs are JSON-RPC 2.0 or above so filling this in is wasteful so while
>>> we�re happy to accept it on input, and even reject requests that specify a
>>> value other than �2.0� we don't reject requests that omit this value and we
>>> *Absence of �id� to indicate that no response should be produced*
>>> *apiVersion:* The specification doesn�t provide a mechanism for
>>> describing different versions on the same API.
>>
>>> Probably because JSON-RPC is a protocol, not an API :D
>>
>>> We added support for this by defining an �apiVersion� field at the top
>>> level of the request which contains a string literal of the version name.
>>> E.g
>>> {
>>> id : �12345�,
>>> method : �language.diacritize.get�,
>>> apiVersion : �v2�
>>> ...
>>> }
>>
>>> This sounds to me like an "encapsulation error" but for communications, as
>>> if rails where to know if the train carried cargo or people ...
>>
>>> Why not :
>>
>>> {
>>> id : �12345�,
>>> method : �v2.language.diacritize.get�,
>>> ...
>>> }
>>
>>> Or just a specific entry point ?
>>
>>> v2.some.api.server.google.com/call
>>
>> See my earlier comment for some context on this. There are some expectations
>> that we need to meet that make this an interesting choice.
>>
>> - People are used to version names with dots in them which makes them a poor
>> choice for valid Javascript identifiers.
>> - We have more than one API under the same namespace with different versions
>> which while not strictly a problem may cause user confusion
>>
>> language.diacritize.v2.get
>> language.translate.v3.get
>>
>> as we cant guarantee that the version if the first literal value in the
>> identifier. This is something we may address by other means in our client so
>> I'm not ruling this out.
>>
>>
>>
>>
>>
>>> {
>>> id : �12345�,
>>> method : �language.diacritize.get�,
Max Kanat-Alexander
> If there's going to be metadata, I'd rather it be "on" the "envelope"
> rather than "in" the envelope, if you know what I mean.
Yeah, agreed. I don't think it would be good for systems to have to
parse and access the parameters before calling the function specified in
"method".
Matt (MPCM)
> On 09/07/2010 07:06 PM, Robert Goldman wrote:
>
> > If there's going to be metadata, I'd rather it be "on" the "envelope"
> > rather than "in" the envelope, if you know what I mean.
>
> Yeah, agreed. I don't think it would be good for systems to have to
> parse and access the parameters before calling the function specified in
> "method".
converted objects in your native language. But, this meaning needs to
live in the method string or be conveyed by the server access path.
Of course that still leaves you with combining both version and path
data and to a question at which level. The cleanest way to do this is
to think of the method string as conveying a path, which might need
additional breaking down/parsing.
Take something like: myNamespace.myGroupingA:v2.myMethodA:v1
It would be reparsed by a server, after json decoding, that understood
this to produce a lookup path like:
['myNamespace','myGroupingA:v2','myMethodA:v1']
First time through the server would see if the path exists, checking
each step for a ":", in effect producing this path lookup:
['myNamespace',['myGroupingA','v2'],['myMethodA','v1']]
Could be objects with properties also, but just an example. The string
path could then be stored against the lookup path of the function for
future faster mapping (or be precomputed depending on your method path
tree).
You could also make the method raw json and have it decoded, but I
would like to see the behavior well spelled out before even
considering changing the specification to allow a complex path object
instead of a marked up path string. I do something like this in
another area of our software(s) and despite being a little non-
traditional, it reads like a DSL for complex path based method
selection.
Plus, this cleanly would fit in an extension specification and not
touch json-rpc 2.0 as it is today.
--
Matt (MPCM)
Matt (MPCM)
been a lot of posts and this might add some perspective thats
relevant.
-------------------------------------------
I am hoping to explain my views a little, and perhaps shed some more
light on the path 2.0 took.
There were a lot thoughts during the times when 1.1 was coming out.
We, the json-rpc yahoo group/community, were having all sorts of talks
about where it should head, what features we wanted, much likes these
recent posts. There where plenty of views and lots of concern.
The spec I assembled at the time was called json-oms (Object Messaging
Specification). I put up a simple page, but the interest was strong
enough that it got folded into json-rpc 2.0 instead of branching as a
separate specification:
http://web.archive.org/web/20080205054113/http://www.json-oms.org/
A lot of what that spec represented in concept made its way into 2.0,
by my and other peoples similar ideas and reactions to 1.0 and what
felt like the looming 1.1WD specification. 1.1WD was tied to http and
in general was much more complex. 1.1WD can be seen in the pages of
this group, for historical reference:
http://groups.google.com/group/json-rpc/web/json-rpc-1-1-wd
My *least* favorite feature in the 2.0 spec is the version. I do not
like it because it suggests that there *should* be future versions,
instead of a minimally evolving core spec with extension
specifications. In fact, that feature was added primarily to offer
backwards compatibility with json-rpc 1.0, not to encourage a point
for future changes to be easily justified. Had json-oms remained
separate, there would never have been a version concept included.
Personally I would love to drop it and really stamp out a simple spec
that looks much more like the json-oms setup. But the community at the
time felt that a version stamp was important. But this is the reason
it exists and lives on today.
Just trying to summarize some of the history around 2.0 as it stands.
--
Matt (MPCM)
Lorenzo Pastrana
> There is no such thing as dual-purpose on the ID field : > > the unique meaning of the ID field is whether the client is listening > or not for a response. > > - ID : "I'm listening on ID slot" > - no ID : "I'm not listening" slot is a transport-specific need
My feeling is this discussion arose because someone got the full picture out of sight, and especially in this case got confused between runtime ID "need" or lack of, and the specification needs.(and even then, or in batch, is not always needed). And that seems to cause some to not even conceive of the obvious third case (and hence not see any dual-purpose). > As said previously the ID is needed in batches and provides the > simplest pivotal point for any transport to be (possibly) > asynchronous. "needs", "needed": This is not true, or this discussion would never have arisen.
in "protocol mindframe" I insist ID is needed
1) to make batches work because batches return values can be in any order
2) to make async response possible
This is not because a certain feature loses some meaning in some runtime condition that the spec doesn't requires the spec.
I'm not sure this is clear enough, you tell me.
Lo.
Lorenzo Pastrana
FWIW, I think it's incumbent on you, as the person who wants to change
the existing spec, to explain to us why this is UNnecessary, instead of
asking us to demonstrate that it is necessary....
Lo.
Lorenzo Pastrana
When you issue a single request in XHR for instance you use the functional callback mechanism in JS to correlate the response with the call so the id is superfluous in this case. We can always have our client produce a synthetic one which has no meaning so it's not a big deal its just for the overwhelming majority of our expected traffic its not needed.
The first is semantic : the "WHEN" you use is actually a specific case, and a runtime one, that case isn't sufficient by itself to drive the whole protocol requirements.
The second is about XHR : in the JSON-RPC spec discussions "asynchronous" has not a transport meaning, I mean even on XHR transport the server's response could need to be asynchronous, the actual implementation chooses. The scenario we discussed about the id is when a call can take, say, an hour to compute and you don't want the client to hold his breath or just timeout in the meanwhile. That would suppose polling a "heartbeat" method from the client if the traffic isn't sustained enough but that's how we thought of this all.
Lo.
Max Kanat-Alexander
> in "protocol mindframe" I insist ID is needed
> 1) to make batches work because batches return values can be in any order
> 2) to make async response possible
Hey Lo.
So, broadly, there are two types of calls:
A) Batch (usually requires ids)
B) Single (sometimes does not require ids)
There are two types of timing:
C) Asynchronous (often requires ids)
D) Synchronous (usually does not require ids)
There are (for the sake of this discussion), two types of transport:
E) A transport which tracks which response is associated with which
request. (does not require ids for single calls, may require them for
batch calls [see below])
F) A transport that does not track which response is associated with
which request. (requires ids for all calls)
And there are two types of batch handling:
G) Returning responses in the same order as the request. (does not
inherently require ids, unless one of the requests is a notification)
H) Returning responses in a random order. (requires ids)
As could be worked out by analyzing the above, there are many valid
combinations above that do not require ids for proper functionality.
There are also many valid combinations above that *do* require ids.
Since there are some combinations that require the id field and some
combinations that do not require the id field, it would make sense to
simply make the id field optional. That way, the conditions that *do*
require an id field (which will be known by API consumers at development
time) can use the id field, and the conditions that don't require an id
field don't have to use it.
Matt (MPCM)
I know you are pushing for making the id optional, but that only works
when you pass that responsibility onto the transport/transport
instance, and that makes a lot of strong assumptions which often are
not true for other usage patterns.
Granted, 80% of the json-rpc calls I make probably do not need an id
with the view you are holding, but allowing the id to be optional
complicates the other meaning that a lack of id currently represents.
Your solution to this is by adding that meaning in again via another
field. This is an change/optimization that is heavily weighed towards
non-notifications, and a lot of change to get there for little gain.
I am not seeing the complication in always sending an {id:""} if your
framework/transport is going to handle the context for you anyway and
you just don't want to deal with it directly.
On Sep 8, 5:32 am, Max Kanat-Alexander <mka...@bugzilla.org> wrote:
> On 09/08/2010 01:29 AM, Lorenzo Pastrana wrote:
>
> > in "protocol mindframe" I insist ID is needed
> > 1) to make batches work because batches return values can be in any order
> > 2) to make async response possible
>
> Hey Lo.
>
> So, broadly, there are two types of calls:
>
> A) Batch (usually requires ids)
> B) Single (sometimes does not require ids)
Batch is a collection of request and responses, they should not be
considered to be in matching order... this was something we discussed
quite a bit in an older thread at the time, if you want to see what
was discussed at the time.
> There are two types of timing:
>
> C) Asynchronous (often requires ids)
> D) Synchronous (usually does not require ids)
Notifications can be sent over sync channels for example. Or requests
over async.
> There are (for the sake of this discussion), two types of transport:
>
> E) A transport which tracks which response is associated with which
> request. (does not require ids for single calls, may require them for
> batch calls [see below])
> F) A transport that does not track which response is associated with
> which request. (requires ids for all calls)
yes... but that also means the client using the transport needs to
understand that. If you a client makes 30 calls to 4 different
servers, having the ids allows a central tabulation of the current
call states. What you are suggesting would require that meaning to be
injected or stored in the currently running transport instances. This
does not work when you want to either freeze the client state, or have
requests that outlive the transport instances. It is not widely used,
but you could have more than one transport type to a server and
messages flowing in and out of different contexts, with the id being
the only way to preserve that ability.
> And there are two types of batch handling:
>
> G) Returning responses in the same order as the request. (does not
> inherently require ids, unless one of the requests is a notification)
> H) Returning responses in a random order. (requires ids)
way... it may not happen that way. Notifications in the batch assure
it doesn't happen that way.
> As could be worked out by analyzing the above, there are many valid
> combinations above that do not require ids for proper functionality.
> There are also many valid combinations above that *do* require ids.
real life, if I hand you a message in an envelope with no id visible
on the outside, and you hand me back a response three days later with
again no id, you better hope I have a really good memory, especially
if I am sending thousands of messages to many different places. What
you are suggestions prevents the client having a simple mechanism (a
table) to keep track of things, and replaces it with lots of
situational awareness, which often can be much more expensive to
recognize and could change from transport to transport.
The best solution is probably to have both, when both are possible.
But both are not always possible at a reasonable cost. Removing the id
because it is possible in some cases does not seem like a good
solution. Even if those cases are the ones that happen often in
current usage.
--
Matt (MPCM)
Robert Goldman
Right. But this might in some cases be more hair than it's worth,
because if the server is implemented in a dynamic language like
JavaScript, the mapping might change, and you would have to have logic
to invalidate the cache...
>
> You could also make the method raw json and have it decoded, but I
> would like to see the behavior well spelled out before even
> considering changing the specification to allow a complex path object
> instead of a marked up path string. I do something like this in
> another area of our software(s) and despite being a little non-
> traditional, it reads like a DSL for complex path based method
> selection.
I'd be reluctant to have the method have decoding applied, because to me
one of the big advantages of the JSON-RPC spec is that it is good for
/cross-language/ RPC. Assigning a semantics to the method name string
seems dodgy because it would impose more constraints on the server
implementation. As I understand things now, the only requirement on the
server is that it somehow translate the method [I wish this were
"procedure," FWIW, since there is no sense in which this is a method,
except possibly a method of the server...] name into a procedure to be
called.
Currently, if the server wishes to interpret the "." as some kind of
scoping or method application operator, there's nothing to stop it, is
there? So it seems like the above suggestion would just impose costs on
compliant servers without providing added function.
Perhaps I'm missing something, but if so, that might be a sign that this
suggestion needs unpacking.
Best,
r
Matt (MPCM)
it is one approach instead of packing more stuff into the request
object/transport layers. Instead of a simple method string, you simply
supply a more meaningful string. It prevents cluttering the request
object with new fields and allows those that `need` that complexity to
much more readily use existing server implementations and just rewrite
the method dispatch/match part of the code.
Dynamic method names are also a way to achieve all sorts interesting
actions while preserving the parameters of the end point function. In
theory you could have the method name be the actual function source
itself, assuming the server understood and allowed it... but that is
very trusting without seriously good sand boxing/protection. I toyed
with this at one point and in non-public systems it has its uses for
rapid light weight distributed computing.
> > You could also make the method raw json and have it decoded, but I
> > would like to see the behavior well spelled out before even
> > considering changing the specification to allow a complex path object
> > instead of a marked up path string. I do something like this in
> > another area of our software(s) and despite being a little non-
> > traditional, it reads like a DSL for complex path based method
> > selection.
>
> I'd be reluctant to have the method have decoding applied, because to me
> one of the big advantages of the JSON-RPC spec is that it is good for
> /cross-language/ RPC. Assigning a semantics to the method name string
> seems dodgy because it would impose more constraints on the server
> implementation. As I understand things now, the only requirement on the
> server is that it somehow translate the method [I wish this were
> "procedure," FWIW, since there is no sense in which this is a method,
> except possibly a method of the server...] name into a procedure to be
> called.
method strings that way, for the rest of the servers it would be no
different handling a non-existent method invocation. Plus, it would be
out of the core spec... which is important in keeping json-rpc simple.
To the client it is just another string, how it knows about such a
complex string is again another matter for outside the spec.
I tend to interchange procedure/method/function... my vote would have
been for function, but if we start posing about json-rfc heads are
going spin ;)
> Currently, if the server wishes to interpret the "." as some kind of
> scoping or method application operator, there's nothing to stop it, is
> there? So it seems like the above suggestion would just impose costs on
> compliant servers without providing added function.
existent method. The client makes the call, but the server decides if
it can handle it.
> Perhaps I'm missing something, but if so, that might be a sign that this
> suggestion needs unpacking.
be done with layering in the existing specification. People think of
the method string as being something very predefined, but it does not
have to be if the server can translate it into something when it needs
too.
To give a somewhat dynamic example, if called a method like this
"some.long.path.{some.long.path.latestVersion}.method", some simple
templating can turn that into something the server understands to be
the most recent version of method. It might be long and ugly, but the
intent is clear in the string.
--
Matt (MPCM)
Lorenzo Pastrana
If the client didn't provide one, you could generate one and use it internally in your library, right?
Only the client knows what the ID is for, the server only echoes it for the client to dispatch responses.
I never said that the "id" field is unnecessary, I simply said that it should be optional
I have demonstrated several cases
To make a protocol operational you must take ALL cases that the protocol covers and make sure they do work and still does when you change something.
The "notification: true" system would
In addition a protocol is not just data, it implies an algorithmic aspect (which is certainly not explicit enough in the spec).
When someone has a pattern that would allow optional ids and would make no assumption on transport, or single call situation, doesn't break notifications, doesn't add ambiguities or under defined zones, has no meaning overlap, fits well in the actual spec (doesn't require to mess everything up), and that can compete with the simplicity of :
Client side :
call_rpc(endpoint,method,params,done)
{
id = new_id();
slots[id] = done;
transport_rpc(endpoint,call,id);
}
Server side :
process_rpc(call)
{
result = execute_call(call.method,call.params);
if(is_defined(call.id))
{
writeout_response(call.id,result);
}
}
Client side
dispatch_response(res)
{
if(is_defined(slots[res.id]))
{
slots[res.id](res);
}
}
Let us know.
Lo.
Yitzchak Scott-Thoennes
> On Tue, 2010-09-07 at 18:12 -0700, Max Kanat-Alexander wrote:
> > If the client didn't provide one, you could generate one and use it internally in your library, right?
> Wrong.
> Only the client knows what the ID is for, the server only echoes it for the client to dispatch responses.
provide one, the client library could generate one.
Robert Goldman
I don't believe that is a correct understanding of Max's argument.
The JSON-RPC spec is handling the case of client library to server
library communication. It doesn't (nor should it) have anything to say
about what API the client library exposes to calling code, nor does it
say anything about how the server library calls methods on the server.
Those are all outside scope.
So if the client library is always going to supply id's, then we should
just keep the mandatory id's in the spec.
It's only if the /client library/, not the calling code, can do without
the id's that we should consider dropping them.
Max's argument relies on the fact that there are client /library/ cases
where there is something about the transport layer which means that
responses will never appear out of order. That is why he argues for the
id being optional in cases where there will be responses.
best,
r
Lorenzo Pastrana
Sorry.
Yitzchak Scott-Thoennes
That's what I was trying to say; that the client library's interface
would not expose id at all, and the client library would generate and
use one for those cases where one was needed but otherwise shouldn't
have to.
Though due to json-rpc's simplicity, I think many of the users in
cases where an id isn't needed won't be using a json-rpc library
at all.
Sean Kinsey
follow the discussion.
If you have some time, read http://jibbering.com/faq/notes/posting/#ps1Post,
the guidelines for compl.lang.javascript.
If not, the at least follow these simple tips:
* Delete most of the message you are responding to except for the
intro (who wrote what when) and the sections that you are responding
to,
this makes it much easier to understand the context, and to see what
you are actually responding to.
Deleted sections are marked with ... or ---.
* Respond *below* the statement/question you are responding to, this
is the natural way to read text. Top-bottom, not bottom-top.
* Do not include the signature of the previous poster as this isn't
part of the message. It also makes it easier to see who signed the
message.
Sean
Louis Ryan
--
You received this message because you are subscribed to the Google Groups "JSON-RPC" group.
To post to this group, send email to json...@googlegroups.com.
To unsubscribe from this group, send email to json-rpc+u...@googlegroups.com.
Louis Ryan
Max,
I know you are pushing for making the id optional, but that only works
when you pass that responsibility onto the transport/transport
instance, and that makes a lot of strong assumptions which often are
not true for other usage patterns.
Granted, 80% of the json-rpc calls I make probably do not need an id
with the view you are holding, but allowing the id to be optional
complicates the other meaning that a lack of id currently represents.
Your solution to this is by adding that meaning in again via another
field. This is an change/optimization that is heavily weighed towards
non-notifications, and a lot of change to get there for little gain.
I am not seeing the complication in always sending an {id:""} if your
Louis Ryan
-API versions:
I don't really see a need to embed version information at the
individual request level. If you want to have multiple versions of a
method available on the same endpoint, using method names with
versions seems reasonable, however I generally prefer the approach of
giving each version of the API it's own endpoint, which is the
approach used by most web services these days. Given that there is no
concept of "api versions" defined or described in the spec, I think
it's a rather heavyweight concept to add just to allow multiple method
signatures with the same name (which is the net result of your
suggestion).
-Dave
Matt (MPCM)
> > I am not seeing the complication in always sending an {id:""} if your
>
> While techincally per-spec I hope we would never recommend anyway do this
> right? It's bad enough dealing with the variance between exact JSON, eval
> parseable blocks and the vagaries of server JSON parsing libraries without
> also encouraging fields that may be omitted or considered NULL equivalents
> in the myriad of backends. This is a good example of something that should
> go in a client library developer guide. I would prefer to use the literal
> 'null' value for this but I expect that is would get silently suppressed in
> some server parsing libraries. 'false' might actually be a better choice.
It was more a frustrated, and ineffective, attempt the point about the
id not being a real complication to include, but it seems there has
been some confusion over the subject that has now been clarified.
client concept role vs client library layering I guess.
There is a note about using null in the spec, because that is how
notifications where done in 1.0 and it could result in mismatching in
batches that contain errors that have bad request objects with clients
that are poorly coded.... phew, that was long sequence.
Clearly there is a lot of room for documentation, pseudo code, real
code, and a need for a documented history around the spec that we can
all benefit from. Especially if interest is picking up in the spec on
the whole, it won't take long to out scale our ability to have
reasonable conversations.
Perhaps this is the time for a renewed effort in generating that
documentation and talking about the specification as it exists today
more. :)
--
Matt (MPCM)
Max Kanat-Alexander
> I know you are pushing for making the id optional, but that only works
> when you pass that responsibility onto the transport/transport
> instance, and that makes a lot of strong assumptions which often are
> not true for other usage patterns.
Hey Matt. :-) Thanks for taking the time to respond. :-)
I don't mean to be pedantic, but what do you mean by "strong
assumption" there? When I read "strong assumption", I tend to interpret
it as meaning, "makes an assumption which must always be true in all cases."
> Granted, 80% of the json-rpc calls I make probably do not need an id
> with the view you are holding, but allowing the id to be optional
> complicates the other meaning that a lack of id currently represents.
> Your solution to this is by adding that meaning in again via another
> field. This is an change/optimization that is heavily weighed towards
> non-notifications, and a lot of change to get there for little gain.
So far, 100% of the JSON-RPC calls I've made haven't needed the id, and
you said above that 80% of yours probably didn't.
It's true that making the id optional complicates the second meaning
that the id represents, which is why I'm suggesting that the id field
should be disambiguated. Disambiguation is good for any protocol or system.
It is indeed heavily weighted toward non-notifications, but I think
that JSON-RPC should in fact be weighted toward non-notifications. In
fact, I think that notifications themselves should have been an
extension spec, and they should not have been a part of the core. One of
the primary reasons that I say that is that I'd estimate that less than
1% of all JSON-RPC traffic currently being generated in the world uses
the notification mechanism, and the vast, vast majority of JSON-RPC
calls are not, in fact, notifications. In fact, I'd guess that the vast
majority of API implementations don't even need the notification
functionality.
> I am not seeing the complication in always sending an {id:""} if your
> framework/transport is going to handle the context for you anyway and
> you just don't want to deal with it directly.
It's not a complexity for *me* that I'm trying to eliminate. I'm an API
implementer and library implementer. The existence or non-existence of
the id field makes no difference to me (except that library
implementation is ever-so-slightly simpler if you don't have to worry
about notifications).
What I'm trying to do is make life easier for consumers, who will
frequently not understand why they have to send an "id" field simply to
get a response, when they thought that they were making a remote
procedure call that would give them some data. "After all, the API docs
say that the function returns data--so why doesn't it return data to
me?" It's the sort of thing that people can spend hours on. I can
promise you that this will be an issue of confusion and frustration for
the many API consumers who have not read through the JSON-RPC spec, and
who, I think, shouldn't have to read through the protocol spec just to
interact with an API.
It's particularly frustrating, as I've mentioned above, in an HTTP GET
situation, although we could certainly mitigate that by making the id
optional *in HTTP GET*. Of course, then you couldn't do notifications
via HTTP GET.
None of this would be a problem if notifications were an extension and
had an unambiguous second field. It could even be called "n" if people
were worried about length.
Matt (MPCM)
> On 09/08/2010 04:37 AM, Matt (MPCM) wrote:
> Hey Matt. :-) Thanks for taking the time to respond. :-)
with google groups. Almost makes me miss my news reader... almost. ;)
> I don't mean to be pedantic, but what do you mean by "strong
> assumption" there? When I read "strong assumption", I tend to interpret
> it as meaning, "makes an assumption which must always be true in all cases."
below.
> > Granted, 80% of the json-rpc calls I make probably do not need an id
> > with the view you are holding, but allowing the id to be optional
> > complicates the other meaning that a lack of id currently represents.
> > Your solution to this is by adding that meaning in again via another
> > field. This is an change/optimization that is heavily weighed towards
> > non-notifications, and a lot of change to get there for little gain.
>
> So far, 100% of the JSON-RPC calls I've made haven't needed the id, and
> you said above that 80% of yours probably didn't.
sequential which block on the server and live well within the HTTP
timeout. But without an id, how would a client match response objects
if such objects outlive the timeout, and perhaps are going to sit for
some time waiting for the client to return later? That id needs to be
available for the eventual mapping. This is really true if there are
json-rpc proxy layers going on behind the scenes...
Lets say the id is optional. A client sends out 40 requests in a rapid
bunch of events and gets 35 back responses right away. No problems so
far. It is still waiting on 5 to return. Then the client goes offline
due to network issues. Then the client comes back online, re-
establishes the transport linkup, and now gets 5 messages, none of
which have ids. What should be done with these call results/errors?
The assumption I am referring to is that the request can only live as
long as the transport time out. But our current setup could be used to
request TheMeaningOfLife() and be able to wait for answer to return in
7.5 million years if need be. I like being able to talk to "Deep
Thought" in theory ;)
> It's true that making the id optional complicates the second meaning
> that the id represents, which is why I'm suggesting that the id field
> should be disambiguated. Disambiguation is good for any protocol or system.
timeout.
> It is indeed heavily weighted toward non-notifications, but I think
> that JSON-RPC should in fact be weighted toward non-notifications. In
> fact, I think that notifications themselves should have been an
> extension spec, and they should not have been a part of the core. One of
> the primary reasons that I say that is that I'd estimate that less than
> 1% of all JSON-RPC traffic currently being generated in the world uses
> the notification mechanism, and the vast, vast majority of JSON-RPC
> calls are not, in fact, notifications. In fact, I'd guess that the vast
> majority of API implementations don't even need the notification
> functionality.
always be a need to send data without caring to know what the other
end does with it. Games are good example here, where data in an MMORGP
about location, orientation, etc. is useful but not vital and goes
stale very fast. Maybe every 3 seconds we actually really care, but
there are some benefits if the client wants to send it every 200ms
without a response overhead. Heartbeats for fail over mechanisms are
another example. Temperature monitors that just yell things out to
servers to propagate.
> > I am not seeing the complication in always sending an {id:""} if your
> > framework/transport is going to handle the context for you anyway and
> > you just don't want to deal with it directly.
>
> It's not a complexity for *me* that I'm trying to eliminate. I'm an API
> implementer and library implementer. The existence or non-existence of
> the id field makes no difference to me (except that library
> implementation is ever-so-slightly simpler if you don't have to worry
> about notifications).
> What I'm trying to do is make life easier for consumers, who will
> frequently not understand why they have to send an "id" field simply to
> get a response, when they thought that they were making a remote
> procedure call that would give them some data. "After all, the API docs
> say that the function returns data--so why doesn't it return data to
> me?" It's the sort of thing that people can spend hours on. I can
> promise you that this will be an issue of confusion and frustration for
> the many API consumers who have not read through the JSON-RPC spec, and
> who, I think, shouldn't have to read through the protocol spec just to
> interact with an API.
making the id optional when it does serve a purpose. Just not in
single call HTTP GET situations. Which may be the majority usage
pattern in the future (or now). If it is optional, there are suddenly
a great deal of other things that need special handling... I think
perhaps this should be discussed in direction relation to HTTP GET and
with examples of your proposed calls/query mapping.
> It's particularly frustrating, as I've mentioned above, in an HTTP GET
> situation, although we could certainly mitigate that by making the id
> optional *in HTTP GET*. Of course, then you couldn't do notifications
> via HTTP GET.
as HTTP GET is often misused... perhaps a thread specific to
addressing this angle of it will lead to some clarity for all of us on
how to move forward.
> None of this would be a problem if notifications were an extension and
> had an unambiguous second field. It could even be called "n" if people
> were worried about length.
the way it is written is being used by people in the community. If
your API suggests that a rpc call is returning data, as opposed to
something like a VB sub or VOID function, that id is needed to map the
result in a variety of other situations that are not single transport
GET calls. It is not exactly like most of these calls are being hand
generated anyway, client libraries would be used to generate these
request objects and make the calls over the transport. Otherwise you
would have to have a generateid() call and keep that list somewhere as
well, unless you also limit the response time to the transport
timeout.
--
Matt (MPCM)
Lorenzo Pastrana
what do you mean by "strong assumption" there? When I read "strong assumption", I tend to interpret it as meaning, "makes an assumption which must always be true in all cases."
It's true that making the id optional complicates the second meaning that the id represents, which is why I'm suggesting that the id field should be disambiguated. Disambiguation is good for any protocol or system.
Max, please read again :
the unique meaning of the ID field is whether the client is listening or not for a response.
- ID : "I'm listening on ID slot"
- no ID : "I'm not listening"
This field setup is coupled to an algorithm which is absolutely simple :
It is indeed heavily weighted toward non-notifications, but I think that JSON-RPC should in fact be weighted toward non-notifications.
You, as an individual, represent 0,0000000145% of the world population, you still have a legitimate existence and a hole bunch of rights.
Nobody can force you to conform to the spec, as well as you cant ask the spec to be restricted to your own specific need because you can't miss what you can't figure.
the id field makes no difference to me
except that library implementation is ever-so-slightly simpler if you don't have to worry about notifications
If you disagree, instead of asserting in the vague, please be specific and provide complete solution that doesn't rely on negating needs you just don't have in your specific case, and provide algorithmic details (see model below).
If you don't, we will just consider the ID question closed for lack of motive.
[quote]
In addition a protocol is not just data, it implies an algorithmic aspect (which is certainly not explicit enough in the spec).
When someone has a pattern that would allow optional ids and would make no assumption on transport, or single call situation, doesn't break notifications, doesn't add ambiguities or under defined zones, has no meaning overlap, fits well in the actual spec (doesn't require to mess everything up), and that can compete with the simplicity of :
Client side :
call_rpc(endpoint,method,params,done)
{
id = new_id();
slots[id] = done;
transport_rpc(endpoint,call,id);
}
Server side :
process_rpc(call)
{
result = execute_call(call.method,call.params);
if(is_defined(call.id))
{
writeout_response(call.id,result);
}
}
Client side
dispatch_response(res)
{
if(is_defined(slots[res.id]))
{
slots[res.id](res);
}
}
Let us know.
Louis Ryan
On Wed, 2010-09-08 at 18:32 -0700, Max Kanat-Alexander wrote:"strong assumption" means that reality could, and certainly will, be different.what do you mean by "strong assumption" there? When I read "strong assumption", I tend to interpret it as meaning, "makes an assumption which must always be true in all cases."It's true that making the id optional complicates the second meaning that the id represents, which is why I'm suggesting that the id field should be disambiguated. Disambiguation is good for any protocol or system.Max, please read again :There is no such thing as dual-purpose on the ID field :
the unique meaning of the ID field is whether the client is listening or not for a response.
- ID : "I'm listening on ID slot"
- no ID : "I'm not listening"
There is actually no need to decouple this bit because both behaviors are mutually exclusive,
This field setup is coupled to an algorithm which is absolutely simple :Why ? Notifications exist and their existence is legitimate.
It is indeed heavily weighted toward non-notifications, but I think that JSON-RPC should in fact be weighted toward non-notifications.
You, as an individual, represent 0,0000000145% of the world population, you still have a legitimate existence and a hole bunch of rights.
Nobody can force you to conform to the spec, as well as you cant ask the spec to be restricted to your own specific need because you can't miss what you can't figure.... what's the point then ?the id field makes no difference to meThat's false because notification won't disappear. Using more than the id field will complicate clients AND servers by orders of magnitude.except that library implementation is ever-so-slightly simpler if you don't have to worry about notifications
If you disagree, instead of asserting in the vague, please be specific and provide complete solution that doesn't rely on negating needs you just don't have in your specific case, and provide algorithmic details (see model below).
If you don't, we will just consider the ID question closed for lack of motive.
[quote][/quote]
In addition a protocol is not just data, it implies an algorithmic aspect (which is certainly not explicit enough in the spec).
When someone has a pattern that would allow optional ids and would make no assumption on transport, or single call situation, doesn't break notifications, doesn't add ambiguities or under defined zones, has no meaning overlap, fits well in the actual spec (doesn't require to mess everything up), and that can compete with the simplicity of :
Client side :
call_rpc(endpoint,method,params,done)
{
id = new_id();
slots[id] = done;
transport_rpc(endpoint,call,id);
}
Server side :
process_rpc(call)
{
result = execute_call(call.method,call.params);
if(is_defined(call.id))
{
writeout_response(call.id,result);
}
}
Client side
dispatch_response(res)
{
if(is_defined(slots[res.id]))
{
slots[res.id](res);
}
}
Let us know.
--
Matt (MPCM)
> On Thu, Sep 9, 2010 at 3:11 AM, Lorenzo Pastrana <pastr...@ultraflat.net>wrote:
> [...]
> final then this is a moot point, if not then lets find out what people are
> doing.
I do not see it as choice between the two, my example is just a
counter-example to why what Max is suggesting should not be the
default behavior. Confusing as some folks might find it.
From my point of view the 2.0 spec is basically final, minus
clarifications or clear errors in the document itself. I am guessing a
lot of others who have been involved with this for a while view it
that way also. That will at least allow us to keep 2.0 as a reference
point in time, just as 1.0, 1.1WD, and 1.1ALT.
If later versions of the specification come out through the community
and bubble up, then at least those of us only desiring 2.0 have a
strong reference point/version number should we decide to stay behind
or use different future extensions. Just like those who only support
json-rpc 1.0 today.
I am hoping Max will start a new thread to discuss his proposal to
remove the id and add a notification flag, especially as it relates to
HTTP GET. Solidify it into an extension specification so we can all
try it out and see the reality it provides. If json-rpc 2.0 +
optional_id_by_default works out, perhaps that will become the next
version of json-rpc. Perhaps it will stay an extension specification,
perhaps it will lead to lots of other better thoughts, but the best
way to address this is to `cook and taste it` and then decide.
--
Matt (MPCM)
Louis Ryan
On Sep 9, 1:48 pm, Louis Ryan <lr...@google.com> wrote:
> On Thu, Sep 9, 2010 at 3:11 AM, Lorenzo Pastrana <pastr...@ultraflat.net>wrote:
> [...]
> why should Matt's behavior be favored over Max's. Again, if the spec isWell, for starters "Matt's behavior" matches the existing spec. :)
> final then this is a moot point, if not then lets find out what people are
> doing.
I do not see it as choice between the two, my example is just a
counter-example to why what Max is suggesting should not be the
default behavior. Confusing as some folks might find it.
From my point of view the 2.0 spec is basically final, minus
clarifications or clear errors in the document itself. I am guessing a
lot of others who have been involved with this for a while view it
that way also. That will at least allow us to keep 2.0 as a reference
point in time, just as 1.0, 1.1WD, and 1.1ALT.
If later versions of the specification come out through the community
and bubble up, then at least those of us only desiring 2.0 have a
strong reference point/version number should we decide to stay behind
or use different future extensions. Just like those who only support
json-rpc 1.0 today.
I am hoping Max will start a new thread to discuss his proposal to
remove the id and add a notification flag, especially as it relates to
HTTP GET. Solidify it into an extension specification so we can all
try it out and see the reality it provides. If json-rpc 2.0 +
optional_id_by_default works out, perhaps that will become the next
version of json-rpc. Perhaps it will stay an extension specification,
perhaps it will lead to lots of other better thoughts, but the best
way to address this is to `cook and taste it` and then decide.
--
Matt (MPCM)
Max Kanat-Alexander
> I am hoping Max will start a new thread to discuss his proposal to
> remove the id and add a notification flag, especially as it relates to
> HTTP GET. Solidify it into an extension specification so we can all
> try it out and see the reality it provides. If json-rpc 2.0 +
> optional_id_by_default works out, perhaps that will become the next
> version of json-rpc. Perhaps it will stay an extension specification,
> perhaps it will lead to lots of other better thoughts, but the best
> way to address this is to `cook and taste it` and then decide.
That sounds like a great idea. :-) Will do (although I'm not sure I'll
get to it today).
Matt (MPCM)
> Can this be made clear on the site? Once thats done then a somewhat formal
> process for how it can be revised can be established. I'm all for making
> things final.
some point in the near future. At the moment this is no formal
process for how it can be revised, we have been a fairly small
community with only a handful of active members that have stuck it out
over the years.
Other than asking group members and managers to vote up/down on
changes as they are suggested, that has been the process. The burden
to make changes is on the person suggesting the changes on really
spell things out, consider the people's concerns, and make the case to
the community if you want them to shift. That's why we felt doing
extension specifications were the easiest path, as even if we can't
all agree, at least there is a way to get what people want/need into
something that can be shared.
Future revisions should not be assumed, or thought of as a quick
process. In that sense, once something is an extension spec and has
been vetted, someone can propose the change be made part of the json-
rpc core spec and things will progress from there.
A lot of us heavily use json-rpc, so people are protective of not
having it being polluted or twisted. This is no one's day job that I'm
aware of... so while perhaps somewhat unfriendly to new comers, it is
best to understand that lots of us have put lots of time over the
years around these concepts and the spec. So there is a certain
terseness that often appears when the existing spec seems to need
defending from people expecting changes to just be made.
Looking forward to the new voices and views, and the resulting
discussions. :)
--
Matt (MPCM)
Lorenzo Pastrana
> I generally agree with Max that the overwhelming majority of use will
> be synchronous HTTP
JSON-RPC was born as a general purpose RPC protocol, and I do hope it
will stay off HTTP predicates.
> Matt's example server which enqueues responses on the server for
> asynchronous delivery to the client across connection issues is a good
> example of why id's are important,
This is why I believe as well as may others that the ID field is
legitimate and necessary, and the spec rather mature on that point. I
must say, even if I didn't took part for now that the thread on errors
n� vs name is much more constructive than this one, however :
> Why should Matt's behavior be favored over Max's.
Because unfortunately Max's proposal (until now) is
very biased toward a particular transport
adds complexity instead of clarifying the spec
makes assumptions that won't be always verified
brakes some cool features of the protocol
but most of all is really incomplete ...
While Matt, me and some others have worked for long on the current spec
and just agrees with it as it is.
> Again, if the spec is final then this is a moot point, if not then
> lets find out what people are doing.
This is why I invited Max or anybody that can come with a clever idea (I
don't have a monopoly upon) to be completely specific and propose a
modification that is mature on all aspects instead of poking around
assertions that are based on the the following terms : Lots of , Most,
Usually, Certain, vast majority etc ...
My point was about the method, not the object.
Additionally I just wanted to clarify what he was about to modify to
make sure the current spec is well understood.
Lo.
Omi
Louis' effort i.e.
Do we put any restrictions on how JSON-RPC is used over HTTP?
I'm pretty sure that my server and client implementations are most
likely not compatible with Matt's for example. Currently I've viewed
the spec as here is a protocol for communicating between a server and
client irrespective of the transport protocol (as such the json might
be encoded or encrypted in the transport but the core of it is still
JSON-RPC 2.0). I recall reading through the JSON-RPC 2.0 over HTTP doc
once but I'm not sure if that ever became a standard. So, do we have
any restrictions (I mean standards) for JSON-RPC 2.0 over HTTP or not?
I'd prefer it if such standards were more like best-practices although
it would be great if we came up with a design that can make different
clients compatible with each server that works over the same protocol.
Rasjid Wilcox
> From my point of view the 2.0 spec is basically final, minus
> clarifications or clear errors in the document itself. I am guessing a
> lot of others who have been involved with this for a while view it
> that way also.
Absolutely. I'd love to see the current version of the 2.0 spec
marked as final. Even though I personally support the idea of string
based errors rather than numeric error codes, I think the current spec
has been well tested and has a number of implementations behind it,
and that changes should happen either as an extension or a new
version.
Cheers,
Rasjid.
Rasjid Wilcox
> There is no such thing as dual-purpose on the ID field :
>
> the unique meaning of the ID field is whether the client is listening or not
> for a response.
>
> - ID : "I'm listening on ID slot"
> - no ID : "I'm not listening"
>
> There is actually no need to decouple this bit because both behaviors are
> mutually exclusive,
I think this is a great explanation, and should probably be written up
somewhere, or even added to the spec as a description of the purpose
of the id field.
In a few lines it explains clearly:
* why no id (ie, a notification) means the server should not send any
response (the client is not listening), and
* why if you don't "care" about the id field, just sending id: 1 for a
request is completely valid (you are saying that the client is always
listening on slot 1)
Cheers,
Rasjid.
Lorenzo Pastrana
On 9 September 2010 20:11, Lorenzo Pastrana <past...@ultraflat.net> wrote: > There is no such thing as dual-purpose on the ID field : > > the unique meaning of the ID field is whether the client is listening or not > for a response. > > - ID : "I'm listening on ID slot" > - no ID : "I'm not listening" > > There is actually no need to decouple this bit because both behaviors are > mutually exclusive, I think this is a great explanation, and should probably be written up somewhere, or even added to the spec as a description of the purpose of the id field.
Lo.
Robert Goldman
> I think what might be helpful to client library implementers is some
> guidance about how to interact with the id'ing mechanism in situations
> such as this. This does not have to be a spec revision but rather a note
> about common usage patterns in common execution scenarios (XHR
> single/batch, true async, etc.). The spec itself is very succinct which
> is a good thing but without additional guidance I think neophytes will
> be likely to raise the same questions over and over just as I did.
>
> I for one would be happy leaving the spec exactly as-is if there was
> some canonical location that implementers could refer to that
> encapsulates the arguments put forth here for why things are the way
> they are. I don't have a problem with the additional bandwidth costs of
> the id in situations where it is theoretically redundant as they can be
> quite useful in incident diagnosis.
Design rationale annotations might be a nice addition to the
specification. I have in mind something where the annotations are kept
easily accessible, but not merged into the spec, so that the spec can be
read without them, or with them.
E.g., an arrangement where the spec can be read online in its unadorned
form, or read in a frames arrangement where the annotations are located
in a frame adjacent to the spec statement. That would be really neat.
best,
r
Robert Goldman
> On 09/08/2010 04:37 AM, Matt (MPCM) wrote:
> What I'm trying to do is make life easier for consumers, who will
> frequently not understand why they have to send an "id" field simply to
> get a response, when they thought that they were making a remote
> procedure call that would give them some data. "After all, the API docs
> say that the function returns data--so why doesn't it return data to
> me?" It's the sort of thing that people can spend hours on. I can
> promise you that this will be an issue of confusion and frustration for
> the many API consumers who have not read through the JSON-RPC spec, and
> who, I think, shouldn't have to read through the protocol spec just to
> interact with an API.
>
I'm afraid I /still/ don't get this point. Why does the consumer ever
have to even know that there is an id field? Shouldn't the client
library be making the JSON-RPC object for the consumer, and then
unwrapping the response object and presenting the consumer with the result?
This point about the consumer recurs, and I feel bad saying this, but it
seems like this will only happen if the JSON-RPC mechanism is
implemented in a way that inappropriately exposes the transport details.
I know it seems rude to say this, but it seems that if a consumer needs
to read the JSON-RPC spec to use an API through a client library, then
that client library is busted, and the consumer should find a different
one. The library should /always/ hide the JSON-RPC object from the
consumer.
Now, if the client library is hiding the JSON-RPC object from the
consumer, then it's really no big deal to have the client library comply
with the requirement for an id. Indeed, arguably it would be /more/
complicated to have the client library worry about whether to add it or
not....
I suppose if you are building a client library that you know is always
going to be operating with synchronous responses, then you might want to
write that library to never have the id. But really, is it /that/
painful to just put an incrementing integer counter into the id field?
Robert Goldman
> On 09/09/2010 07:48 PM, Louis Ryan wrote:
>
>> I generally agree with Max that the overwhelming majority of use will
>> be synchronous HTTP
>
> JSON-RPC was born as a general purpose RPC protocol, and I do hope it
> will stay off HTTP predicates.
FWIW, the reason I like JSON-RPC is that it provides a nice RPC protocol
over sockets. Whatever the advantages/disadvantages, I can live with
AJAX or the equivalent using JSON. So the big win in JSON-RPC for me is
that it lets me use other transport protocols without having to eat an
elephant like SOAP or CORBA....
Best,
r
Vladimir Dzhuvinov
I see new ideas and proposals are coming to JSON-RPC, but please,
leave the current 2.0 version as it is :) I would be happy if a newer
and even better protocol version appears, but as for 2.0 I would very
much like to see it marked as final so I can have my peace of mind :)
Since the end of 2009 when the 2.0 proposal stabilised I have
developed a Java library for it and now my business is relying on 2.0
for a number of important products, such as the Json2Ldap web service
for LDAP v3 compatible directories. Users have also more or less
assumed that the 2.0 spec is stable now and won't be subject to
change.
Vladimir
--
Vladimir Dzhuvinov :: software.dzhuvinov.com
Yitzchak Scott-Thoennes
> On 9/8/10 Sep 8 -8:32 PM, Max Kanat-Alexander wrote:
> > What I'm trying to do is make life easier for consumers, who will
> > frequently not understand why they have to send an "id" field simply to
> > get a response, when they thought that they were making a remote
> > procedure call that would give them some data. "After all, the API docs
> > say that the function returns data--so why doesn't it return data to
> > me?" It's the sort of thing that people can spend hours on. I can
> > promise you that this will be an issue of confusion and frustration for
> > the many API consumers who have not read through the JSON-RPC spec, and
> > who, I think, shouldn't have to read through the protocol spec just to
> > interact with an API.
> >
>
> I'm afraid I /still/ don't get this point. Why does the consumer ever
> have to even know that there is an id field? Shouldn't the client
> library be making the JSON-RPC object for the consumer, and then
> unwrapping the response object and presenting the consumer with the result?
>
> This point about the consumer recurs, and I feel bad saying this, but it
> seems like this will only happen if the JSON-RPC mechanism is
> implemented in a way that inappropriately exposes the transport details.
For better or worse, the JSON-RPC spec suffers from the flaw that many
clients or servers will not use a separate json-rpc library layer
because it's so d*mn simple.
> I know it seems rude to say this, but it seems that if a consumer needs
> to read the JSON-RPC spec to use an API through a client library, then
> that client library is busted, and the consumer should find a different
> one. The library should /always/ hide the JSON-RPC object from the
> consumer.
That seems inconsistent. Take a hypothetical API using HTTP. Either
the API documentation will just say "uses JSON-RPC" and then refer to
"error", "params", "result", etc. where needed (in which case a client
will need to read the JSON-RPC spec to know what that means) or the API
documentation will include full examples of JSON-RPC requests and
responses and have to explain why "id" is needed even though this is
synchronous transport.
Unless you are proposing that an HTTP-based API designer go and find and
test json-rpc libraries to suggest people use for every possible client
language? That's a never-ending task, even if such libraries existed
for more than a fraction of the possible client languages.
I'm completely mystified what it is you expect API documentation to tell
the prospective consumer.
Gaetano Giunta
What I have implemented so far on the server-side is:
. the server passes to user-code function a 'request' object, where the incoming id is available if the end-user code wants to inspect it
. user-code function returns a 'response' object, where id is not needed. Server injects original id in the response while serializing it
. what if the user-code function returns a 'response' object where the id has been changed from the received one? So far this is not handled at all (ie. id will
be overwritten with the server's one)
On the client side:
. the user-code needs to pass to the 'client' obj a 'request' obj. The id field has to be managed by user-code (currently passed as param to the constructor to
the 'request')
advantage: in case the server needs specific IDs, user-code can use them
disadvantage: user-code needs to always manage those pesky ids by itself
An evolution could be to hide management of ids from the client-side user code, too: either by creating a getnewid() method that would return a unique id every
time, or by removing the id from the constructor of the the 'request' obj and making it completely transparent to user-code.
Q1: is any real-life server using IDs which have a specific meaning / format and would not work if every request received was an increasing integer number?
Q2: what approach has been chosen so far by other implementors?
Keep in mind that having a library API that is compatible with spec version 1.0 is considered a bonus in my case.
Bye
Gaetano
Yitzchak Scott-Thoennes
> As a jsonrpc-over-http toolkit implementor I am in fact more concerned about the "always-hide-id from end user" pattern on the client side than server.
>
> What I have implemented so far on the server-side is:
> . the server passes to user-code function a 'request' object, where the incoming id is available if the end-user code wants to inspect it
> . user-code function returns a 'response' object, where id is not needed. Server injects original id in the response while serializing it
> . what if the user-code function returns a 'response' object where the id has been changed from the received one? So far this is not handled at all (ie. id will
> be overwritten with the server's one)
>
> On the client side:
> . the user-code needs to pass to the 'client' obj a 'request' obj. The id field has to be managed by user-code (currently passed as param to the constructor to
> the 'request')
> advantage: in case the server needs specific IDs, user-code can use them
> disadvantage: user-code needs to always manage those pesky ids by itself
> An evolution could be to hide management of ids from the client-side user code, too: either by creating a getnewid() method that would return a unique id every
> time, or by removing the id from the constructor of the the 'request' obj and making it completely transparent to user-code.
>
> Q1: is any real-life server using IDs which have a specific meaning / format and would not work if every request received was an increasing integer number?
>
> Q2: what approach has been chosen so far by other implementors?
So far as I've heard, people are universally *never* using the json-rpc
id for anything that would "have a specific meaning" to the user code
on the server or on the client.
I think you are making things much more complicated than they need to be
by trying to support that. If an id is meaningful to the remote
procedure, it belongs in the params object. If an id is meaningful to
the client-side user code, it belongs in the result or error object.