Story #1906: Review, revise, and update architecture documentation
Split the CN API into public and private sections
Consider splitting the methods of the Coordinating Node API into a private and a public part.
The private part would include all methods that facilitate communication only between CN components. The public part would include methods that are designed for use by MNs and clients.
Also, consider splitting any types used by the private methods out to a private schema as well.
Splitting the API into a private and public part would have the following advantages:
- It would allow us to change the private methods, and the types used by those methods, at any time.
- It would be help for MN and client developers not to have to see the internal CN methods in the docs.
- Only the public API would have to be versioned and could be by itself below /v1/.
- The private API could be separated out, for instance below /private/.
- Changes to the private API would not require modifications to the public docs.
It could have the following disadvantages:
- Changing the status of an API from private to public would require making a duplicated REST endpoint for under the versioned namespace.