docs: document rpc api versioning process.

[dnldd]

This documents the process expected to be followed by contributors in versioning JSON-RPC API endpoints.

work towards #2746.

[matthawkins90]

I think this update is awesome. Had a quick question.

From the previous issue, the two main approaches are:

1. A single versioned endpoint for the entire RPC API, or
2. Individual versioned endpoints for each RPC method.

I just want to clarify what you mean by "Per-RPC Versioning" and "versioned per-RPC endpoint" When you say those words, are you referring to the 2nd approach above, or just that the RPC API will have versions in general?

(The reason I ask is because I also couldn't tell from the previous issue which approach you were going to move forward with. But the pro/con writeup was definitely helpful)

[dnldd]

After discussing the two approaches in chat with davec, versioning each RPC individually was the better approach and that is what this versioning process recommends. "Per-RPC Versioning" and "versioned per-RPC endpoint" are all referring to individual versioned endpoint for each RPC method here. Open to suggestions on wording it better. I will update the text to clearly indicate this where it unclear. I was supposed to comment on the issue regarding the preferred approach before writing the docs, missed a step there.

[matthawkins90]

Looking really good, and I like this schema.
Hopefully my comments are clear and helpful!

[matthawkins90]

I like the word streamline, but I think this sentence could be worded a bit better. I stumbled over it a few times. I also tweaked some of the language about "versioning endpoints" to be as clear as possible, I hope. See what you think.

"To prevent API compatibility issues when when transitioning between release versions, dcrd's JSON-RPC API methods will each have an individually versioned endpoint. Per-method endpoint versioning provides the flexibility needed to isolate the development of each method, and allows each method to evolve individually and exclusively from each other."

My thought process is:

• RPC is a protocol (adjective)
• The API is the general category (noun)
• The method is the main "thing" we're talking about.
• The endpoint is the way to access the main thing
• The endpoints are what are changing, but they're the method endpoints.

[dnldd]

Yeah, I think that's clearer. Will make the changes.

[dnldd]

I'm going to leave this in draft still and look to add a section for versioning websocket endpoints.

[matthawkins90]

I think the comments and structure makes sense. Unfortunately, I'm only a novice with golang, so I can't really comment on the code examples.

[matthawkins90]

This last sentence is clunky, and I'm not sure what you're trying to say. Is this a list of remaining steps to take before the new versioned endpoints API can be active? I don't really understand the second half of the sentence, but I gave it my best shot. Please feel free to modify:

Once all dcrd JSON-RPC API methods are updated using the schema outlined above, the versioned endpoints will be ready for use. However, dcrctl and other consumers will need to update their rpc/jsonrpc/types dependencies and logic.

[dnldd]

I'm saying dcrctl needs to be rebuilt with the updated jsonrpc types dependency to be able to access the new versioned commands.

[dnldd]

Just realized having the default method name resolve to the current version of the endpoint will break consumers once they update. We don't want that, should be resolving to the older version instead. Will make the needed changes soon.