Loading ...
Sorry, an error occurred while loading the content.
 

WD1.1 suggestions for a simple json-rpc

Expand Messages
  • r.koebler@yahoo.de
    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
    Message 1 of 7 , Mar 25, 2007
      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
    • Jim Washington
      ... 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
      Message 2 of 7 , Apr 3, 2007
        r.koebler@... 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
      • Gaetano Giunta
        ... Sorry, imho it is a confusing feature in general, and it is not implemented consistently across languages / environments myfunc( hello , firstparam =
        Message 3 of 7 , Apr 4, 2007
          > What is wrong with mixed named and positional parameters?
          Sorry, imho it is a confusing feature in general, and it is not implemented consistently across languages / environments
           
          myfunc('hello', firstparam = 'world') ==> is the first param hello or world? is it a valid call?
          myfunc('hello', debug=true, 'world') ==> is the third param world or is it the second?
          what about parameters that are optional vs. mandatory?
           
          etc...
           
          I would really rather have two different calling conventions available.
           
          All the "dumb" languages can then expose a positional-only webservice api and, if need be, use a struct as single method parameter, and retrieve the struct members inside (or use the toolkit to implement named-aparemters call).
           
          Otoh, forcing mixed-convention call means a huge pile of cruft has to be implemented in toolkits.
           
          Bye
          Gaetano
        • Jim Washington
          ... I know that in python, these issues are handled as exceptions and/or syntax errors. This mixed model is not confusing in python. The convention is that
          Message 4 of 7 , Apr 4, 2007
            Gaetano Giunta wrote:
            > > What is wrong with mixed named and positional parameters?
            > Sorry, imho it is a confusing feature in general, and it is not
            > implemented consistently across languages / environments
            >
            > myfunc('hello', firstparam = 'world') ==> is the first param hello or
            > world? is it a valid call?
            > myfunc('hello', debug=true, 'world') ==> is the third param world or
            > is it the second?
            > what about parameters that are optional vs. mandatory?
            >
            I know that in python, these issues are handled as exceptions and/or
            syntax errors. This mixed model is not confusing in python. The
            convention is that all named parameters in a call follow all positional
            parameters.

            > etc...
            >
            > I would really rather have two different calling conventions available.
            That's fine with me, too. I have suggested separating them in JSON-RPC
            syntax. I concur with the majority here that mixing them together in
            the "params" member is ugly. I have suggested that the params member
            remain an Array, ([]), and that there be another member, kwparams, which
            is a struct ({}), that would be the location for any named parameters.
            This would be sufficient for my purposes and would accommodate the
            calling conventions for most (all?) server language(s). If the server
            language does only positional parameters, use the "params" member. If
            the server allows named parameters, you may use the "kwparams" member.
            Use them both together if the server language allows.

            I fear that I will need to keep repeating this until "the light goes on"
            and this community understands that this is not only useful but simpler
            to implement than the WD as it stands.

            >
            > All the "dumb" languages can then expose a positional-only webservice
            > api and, if need be, use a struct as single method parameter, and
            > retrieve the struct members inside (or use the toolkit to implement
            > named-aparemters call).
            The problem with this is that there is no convention for this. What
            toolkit does this?
            >
            > Otoh, forcing mixed-convention call means a huge pile of cruft has to
            > be implemented in toolkits.
            Not so much, if you separate named and positional as I recommend.

            -Jim Washington
          • r.koebler@yahoo.de
            hi, ... it s complicated and not really useful. and it adds new errors. ... I hope you don t really use param1 and param2 as parameter-names... ... that s
            Message 5 of 7 , Apr 7, 2007
              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
            • r.koebler@yahoo.de
              ... and so, mixed and positional parameters add new error-cases which do not exist without them, and which are probably confusing for some programmers/users.
              Message 6 of 7 , Apr 7, 2007
                On Wed, Apr 04, 2007 at 07:09:00AM -0400, Jim Washington wrote:
                > Gaetano Giunta wrote:
                > > > What is wrong with mixed named and positional parameters?
                > > Sorry, imho it is a confusing feature in general, and it is not
                > > implemented consistently across languages / environments
                > >
                > > myfunc('hello', firstparam = 'world') ==> is the first param hello or
                > > world? is it a valid call?
                > > myfunc('hello', debug=true, 'world') ==> is the third param world or
                > > is it the second?
                > > what about parameters that are optional vs. mandatory?
                > >
                > I know that in python, these issues are handled as exceptions and/or
                > syntax errors.
                and so, "mixed and positional parameters" add new error-cases which do
                not exist without them, and which are probably confusing for some
                programmers/users.

                > This mixed model is not confusing in python.
                don't rely on python -- the json-rpc-specification must be
                language-independant.

                > If the server
                > language does only positional parameters, use the "params" member. If
                > the server allows named parameters, you may use the "kwparams" member.
                > Use them both together if the server language allows.
                and if the server language doesn't allow?

                > I fear that I will need to keep repeating this until "the light goes on"
                > and this community understands that this is not only useful but simpler
                > to implement than the WD as it stands.
                yes, this would be better than the WD1.1 (although it introduces additional
                overhead). but that's the wrong way. in my opinion, its *much* better to
                omit this mixing at all.


                regards,
                Roland
              • r.koebler@yahoo.de
                hi again, (answering myself ;)) ... but unfortunately, to be able to make this translation, the client would have to know the methods and its parameter-names.
                Message 7 of 7 , Apr 9, 2007
                  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
                Your message has been successfully submitted and would be delivered to recipients shortly.