Runtime api documentation

[kostekIV]

I feel like the documentation that references runtime api and in particular documentation from sp-api and executor crate is missing some important informations.

List of Missing informations that I couldnt find in documentation but have to go through a lot of code to get and Im still not sure if I understand it well enough:

• combinations of [old/new] runtime X [old/new] client, which apis are available & what code gets executed?
  • Envision situation when we have changed the logic of the existing runtime api. Which logic is executed in scenarios where we have new client but old runtime and which logic is executed when we have new runtime but old client?
• Calling apis on old blocks with different runtime
  • which runtime is used?
  • can you use api that was not yet defined at that point in the old runtime?
• What are best practices/recommendations to make apis backwards compatible?
  • logic changes
  • struct definitions changes in the runtime
  • api_version macro - I may not understand it well but is it mostly for situation when we want to have multiple versions of the same function in single runtime?

What, in regard to runtime api, will change after native free world? Should we prepare for any major refactoring?

[bkchr]

• Envision situation when we have changed the logic of the existing runtime api. Which logic is executed in scenarios where we have new client but old runtime and which logic is executed when we have new runtime but old client?

The implementation of the runtime api always depends on the on the runtime you are calling into. Not really related to the node version (assuming function name/signature) didn't changed.

• which runtime is used?

The one that was active at the block you are calling into.

• can you use api that was not yet defined at that point in the old runtime?

No.

• api_version macro - I may not understand it well but is it mostly for situation when we want to have multiple versions of the same function in single runtime?

No. If you do changes that change the signature/name/add a new function you should bump the version. This version is basically an identifier that you can use in your node code to find out which api version the runtime is supporting to call the appropriate function etc.

[kianenigma]

https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/custom_runtime_api_rpc/index.html might help.