search

kbaseincubator / jsonrpcbase

MIT License
0 stars 0 forks source link

JSON-RPC NOQ (non-obvious questions) #19

Open xpe opened 4 years ago

xpe commented 4 years ago

Until we get the wiki feature enabled, I'd like to jot down some Non-Obvious Questions (NOQ).

xpe commented 4 years ago

Topic: Namespaces

The JSON-RPC spec does not say anything about namespaces (e.g. packages, modules, classes, and so on). With this in mind, what are some good ways to design an API?

The string value of the method property should represent the string you expect your consumers to use. That may not always be the literal mapping to the method name in a class in a namespace, but really depends on your consumers expected knowledge into your system. - Matt (MPCM), 8/24/16

Matt gives justification, next:

Requiring extra scoping via additional namespace and className properties breaks with the spirit of the spec, in that existing clients would not send those values. In this case those values are essential to processing the request in your example, so they need to be part of the method string, or part of the params that get reshuffled before internal invocation.

For related discussion, see:

xpe commented 4 years ago

Topic: Do Extra Fields Violate the JSON-RPC spec?

I am writing a JSON RPC conform js library. Are clients allowed by the specification to add custom fields (e.g. headers) along the params field to Request objects? - Henning's question; full title below

You are right in that the Specification does not mention anything about additional fields. So legally-speaking, if it is not forbidden, it is allowed. - Torben Klein's answer

References:

xpe commented 4 years ago

Topic: Internal Error vs Server Error

Is there a rule of thumb to decide if something should be called an internal error over a server error? - Adam Levy

My personal feeling is that if it's a "bug", i.e., a programmer doing something wrong, that's an Internal error, whereas a Server error is something anomalous out of the programmers control, such as loss of connectivity to a database. - Derrell Lipman

jayrbolton commented 4 years ago

Thoughts on a couple topics above:

Namespaces

If you want two namespaces under the same http service, my suggestion would be to create two paths, /namespace1 and /namespace2 that respond with separate JRPC services. KBase has a convention of doing "ModuleName.method_name" for all methods, but I don't see any point to that.

Extra fields

Very ambiguous, but I would vote that kbase services respond with an error