decred
docs: document rpc api versioning process.
This documents the process expected to be followed by contributors in versioning JSON-RPC API endpoints.
work towards #2746.
I think this update is awesome. Had a quick question.
From the previous issue, the two main approaches are:
- A single versioned endpoint for the entire RPC API, or
- 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)
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.
I'm going to leave this in draft still and look to add a section for versioning websocket endpoints.
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.