search

varlink / varlink.github.io

The Varlink Website
https://varlink.org
Apache License 2.0
34 stars 10 forks source link

improvements to FAQ section on extending interfaces #18

Open bonzini opened 4 years ago

bonzini commented 4 years ago

Among the various strategies for extending APIs, the FAQ does not mention making an existing arguments optional. Here is a contrived example:

-   method debug(parts: [string]()) -> (result: [string]object)
+   # Include all possible debugging info if the argument is null
+   method debug(parts: ?[string]()) -> (result: [string]object)

This is backwards-compatible on the wire, but would entail backwards-incompatible changes in some language bindings (for example in Rust the argument would be wrapped by Option<>). Related to this, the FAQ should also clarify that extending the protocol by adding new optional method arguments might break language bindings, and whether that's an acceptable, unacceptable or merely impolite thing to do.

I can prepare a pull request if you give me the answers. :)

haraldh commented 4 years ago

This is backward compatible for updating servers. So, client with new protocol and old server will not work of course, if the optional is left out; except if you handle the failure for old servers and provide the optional.

haraldh commented 4 years ago

I would say, that part should be documented for clients wanting to handle old servers and then it should be ok with the language bindings.

haraldh commented 4 years ago

Of course, if the optional is in the return parameters, you have a problem as a new server with all the old clients.