WD1.1 suggestions for a simple json-rpc

hi,

I like JSON-RPC 1.0: it's nice and simple.
And its *simplicity* is its major advantage to all other rpc-systems.
The JSON-RPC 1.1WD then added some very useful features (like named
parameters).

But unfortunately, the JSON-RPC 1.1WD also lost this simplicity, making
json-rpc rather complex and complicated. Requiring HTTP, allowing mixed
named and positional parameters and some other things increase the
complexity, but rarely add any benifit. They even made it unusable
for some applications.

According to some mails on this list, I'm not the only one with this
opinion.

So, I tried to remove this complexity, and now I think I've got
something which is (nearly) as powerful as the 1.1WD but still
simple like JSON-RPC 1.0.

But instead of writing all these things into a maybe large mail,
I've put it onto a website: http://84.16.237.14/jsonrpc/
There you can find both the (main) differences to 1.1WD and
a whole specification with all my suggestions, derived from
the 1.1WD.
I think this would be an improvement to 1.1WD.

I will probably also write a python server and client according
to this.

please tell me what you think about it.

thanks,
Roland

Messages in this topic (1) Reply (via web post) | Start a new topic

.

r.koebler%40yahoo.de">r.koebleryahoo.de wrote:
> hi,
>
> I like JSON-RPC 1.0: it's nice and simple.
> And its *simplicity* is its major advantage to all other rpc-systems.
> The JSON-RPC 1.1WD then added some very useful features (like named
> parameters).
>
> But unfortunately, the JSON-RPC 1.1WD also lost this simplicity, making
> json-rpc rather complex and complicated. Requiring HTTP, allowing mixed
> named and positional parameters and some other things increase the
> complexity, but rarely add any benifit. They even made it unusable
> for some applications.
>
>
What is wrong with mixed named and positional parameters?

def myFunc(param1,param2,debug=False,verbose=1):
[...some cool code...]
return result

I see that you use python. The above is a perfectly good python
function declaration, with mixed named and positional parameters.

The named parameters are optional. If you choose to include them in the
invocation of the method, you may, but they are not necessary, because
default values are provided.

This is useful.

I can call

1. myFunc(1,2)
2. myFunc(3,4,debug=True)
3. myFunc(5,6,verbose=9)
4. myFunc(7,8,False,7)
5. myFunc(param1=5,param2=6,debug=False,verbose=9)

In call #1, above, the optional parameters are not used. In calls #2
and #3, one of the named parameters is used, and the other is not.
These are the mixed case examples. Note that, if there were many more
optional parameters, any subset of them could be used, in any order,
without adversely affecting any default values. In call #4, the call is
done by positional arguments. Note that in call #4, the default
parameter, debug, must be used with its default value in order to use a
non-default value for verbose. In call #5, the call is done only using
named arguments. In this case, every parameter to the last one used
must be named and given a value. Call #5 is equivalent to call #3.

JSON-RPC provides a way to call remote procedures. Eliminating the
ability to call mixed named and positional parameters is a mistake. You
may not like the method proposed in WD1.1, (indeed, I think the ugly
syntax for this is probably the major sticking point, not the idea
itself) but eliminating the functionality is a mistake.

I have proposed an alternative, less-ugly, syntax to allow mixed
positional and named parameters, on this list. If the ugliness of the
syntax in WD1.1 is the important factor in removing this functionality,
please consider using my alternative syntax for it.

-Jim Washington

Messages in this topic (0) Reply (via web post) | Start a new topic

.

hi,

> What is wrong with mixed named and positional parameters?
it's complicated and not really useful. and it adds new errors.

> def myFunc(param1,param2,debug=False,verbose=1):
> [...some cool code...]
> return result
I hope you don't really use "param1" and "param2" as parameter-names...

> I see that you use python. The above is a perfectly good python
> function declaration, with mixed named and positional parameters.
> The named parameters are optional.
that's wrong:
- *every* parameter has a name.
- a parameter is optional if it has a *default-value*.
please don't mix that up.

> If you choose to include them in the
> invocation of the method, you may, but they are not necessary, because
> default values are provided.
>
> This is useful.
yes, optional parameters are useful.
but this doesn't have to do *anything* with mixing named and positional
parameters.

> I can call
>;
> 1. myFunc(1,2)
> 2. myFunc(3,4,debug=True)
> 3. myFunc(5,6,verbose=9)
> 4. myFunc(7,8,False,7)
> 5. myFunc(param1=5,param2=6,debug=False,verbose=9)
you should notice that there are 2 different things:
a) json-rpc-protocol: the communication between server and client.
b) your programs: there you can create functions for the server
and call functions from the client (via a json-rpc-proxy).

please recognize that these are 2 nearly-*independent* parts!!
this list is about (a), but you seem to talk about (b).

or, in your examples:

a) json-rpc-protocol / communication:
1. {... "method": "myFunc", "params" : [1,2] }
2. {... "method": "myFunc", "params" : [3,4], "kwparams" : {"debug":True} }
3. {... "method": "myFunc", "params" : [5,6], "kwparams" : {"verbose":9} }
4. {... "method": "myFunc", "params" : [7,8,False,7] }
5. {... "method": "myFunc", "params" : {"param1":5, "param2":6, "debug":False, "verbose":9} }
6. {... "method": "myFunc", "params" : {"param1":3, "param2":4, "debug":True }
7. {... "method": "myFunc", "params" : {"param1":5, "param2":6, "verbose":9 }
#2 and #3 are in your syntax, not in the one described in WD1.1
#6 is equivalent to #2, #7 is equivalent to #3.

and now, please tell me what you think that are the advantages of 2 and 3
over 6 and 7. Because I can't see any.

b) your program:
here, you can call the rpc-functions as you like, in any way your proxy
supports. if your language (and your json-rpc-proxy) support the mixing
of "named and positional parameters", you can of course use them.
but you don't need "mixed named and positional parameters" in the
json-rpc-specification for this!

in python, you could i.e. write:
>>> myFunc( 5,6,verbose=9 )
this then would be translated by the proxy to:
{... "method": "myFunc", "params" : {"param1":5, "param2":6, "verbose": 9 }

again: the json-rpc-specification only says how the communication looks like.

> Note that, if there were many more
>; optional parameters, any subset of them could be used, in any order,
> without adversely affecting any default values.
that's also possible with only named parameters.

> In call #4, the call is
> done by positional arguments. Note that in call #4, the default
> parameter, debug, must be used with its default value in order to use a
> non-default value for verbose.
If you want to use the default-value of a parameter, I **strongly recommend**
to omit it. (and if you don't understand why, think about it until you do.)

> Call #5 is equivalent to call #3.
no, it isn't. "myFunc(param1=5,param2=6,verbose=9)" would be equivalent
to #3.

> JSON-RPC provides a way to call remote procedures. Eliminating the
> ability to call mixed named and positional parameters is a mistake.
no, I don't think so. eliminating "mixed named and positional
parameters" makes json-rpc more simple:
- normally, you should always use json-rpc with named parameters.
the advantages are listed both on the WD1.1 and on my proposal.
- if you don't like the overhead of named parameters or cannot
parse/create named parameters (i.e. very small embedded systems,
fast realtime-communication etc.), you can use positional
parameters.

but I don't see *any* case where mixing them in the json-rpc-protocol
would have any advantage.

regards,
Roland

Messages in this topic (0) Reply (via web post) | Start a new topic

.

hi again,
(answering myself ;))

> a) json-rpc-protocol: the communication between server and client.
> b) your programs: there you can create functions for the server
> and call functions from the client (via a json-rpc-proxy).
>
> please recognize that these are 2 nearly-*independent* parts!!

> in python, you could i.e. write:
> >>> myFunc( 5,6,verbose=9 )
> this then would be translated by the proxy to:
> {... "method": "myFunc", "params" : {"param1":5, "param2":6, "verbose": 9 }
but unfortunately, to be able to make this translation, the client would
have to know the methods and its parameter-names. although this would be
possible i.e. with WSDL, it's much better if it also works without.

so, you're right Jim, using "mixed" positional and named parameters may
be handy, so that you can i.e. use "myFunc( 5,6, verbose=9 )" without
additional knowlege (like WSDL).

but I would still recommend to *always* use named-parameters, because:
- the call appears more readable and self-contained on the wire, which
can aid in logging and diagnosis without having to constantly consult
the procudure definitions.
- the client gains independence from any change in the order of the
formal argument list.

but ok, if you know these disadvantages and still want to use mixed
named+positional parameters, we would need a simple definition, how
this should look like:

- {... "method": "myFunc", "params": {"0": 5, "1": 6, "verbose": 9} }
this is what WD1.1 says, but which I think is *bad*. this assumes that
there are no parameters named "0", "1" etc. and it makes the
implementation more complex.

- {... "method": "myFunc", "params": [5,6], "kwparams": {"verbose": 9} }
this is what Jim suggested. but this can be problematic with
json-rpc 1.0 servers, because they probably simply ignore "kwparams"
and so *silently* return wrong results. so the client MUST always
check the returned version string.

so, I would recommend to use Jim's suggestion for mixed parameters,
because:
- explicit is better than implicit
- you directly see if the call uses positional, named or both parameters,
without having to parse the dictionary. so this shouldn't add any
complexity to implementations which do not support mixed/named parameters.
- and I don't really see the advantages Atif mentioned for the WD1.1
approach in message 267.

the param-positions should be defined like in python. if a parameter is
both given as named and positional parameter, an error must be returned.

and every json-rpc-implementation then:
- MUST support positional parameters (via params)
(because it is very simple to implement this, and so I think it would
be really stange to make this optional.)
- SHOULD support named parameters (via kwparams),
(so every "unconditionally complient" implementation must support
this.)
- MAY support both in 1 call (via params+;kwparams)

- MUST return an error if it is called with kwparams or
params+;kwparams and does not supported this.

QUESTIONS to YOU:
- what do you think about this?

- should these "mixed" parameters be allowed at all?
do we really need "myFunc(5,6,verbose=9)" with all its disadvantages,
when we can/should use "myFunc(a=5,b=6,verbose=9)" ?

- is there a better name for "kwparams"?
("namedparams", "nparams", "kwparams", ...?)

- should named-parameters be also allowed via params (instead of kwparams)?
according to the above definition, a call with only named-parameters
would look like:
{... "method": "myFunc", "kwparams": {"a": 5, "b": 6, "verbose": 9} }

this question is, if:
{... "method": "myFunc", "params": {"a": 5, "b": 6, "verbose": 9} }
should be allowed, too. (but then, of course, no additonal "kwparams"
would be allowed).
I would probably say no.

regards,
Roland

Messages in this topic (0) Reply (via web post) | Start a new topic

.