Purpose

It should be possible to report deprecation warnings back to RPCAPI clients. This would allow us to update the APIs in a friendlier fashion.

Scope

This issue is about creating a channel or making room for delivery of deprecation warnings. It is not about introducing deprecation warnings.

Design

1. For each API method that today puts a scalar or an array in its top-level "result" property:
   1. Copy this method to a different name.
   2. Change the response object of the new method so that the top-level "result" property is an object instead of a scalar or array. Let the new object have a single property with the scalar/array data as its value.
   3. Mark the original methods as deprecated in the API documentation with a note encourage clients to migrate to the new method.
2. For each method in the API, add an optional property in the top-level "result" object. Let the new property be named "warnings" and let it have a non-empty list of human readable strings as its value.

Implementation-wise you'd probably have one method call the other and just modify the result. Documentation-wise you'd probably do something similar.

It would be nice if we could have the old methods emit deprecation warnings when you use them, encouraging clients to migrate to the new method. But that's exactly the problem with those methods. We can't. And that's exactly why they're being replaced.

Alternatives

• Instead of adding a "warnings" property into the "result" object, we could add it to the top-level response object. However I don't think it's allowed in the JSON-RPC 2.0 specification, and I'm not sure we could coax JSON::RPC into doing this.
• Instead of giving immediate feedback about deprecated usage in the response object, we could introduce a new method that clients to poll to receive warnings generated in previous calls. It's not clear what mechanism we'd use to give the right deprecation warnings to the right client.
• Instead of giving immediate feedback about deprecated usage through the RPC-API, we could announce deprecations through documentation only. E.g. in the API documentation and release notes.