What is the best way to version paths?
I know there is a version enumeration in the servers block, but that is for endpoint generation in the rendered swagger document. I'm looking for a way to manage the paths when I have changes to the ...
Forum Discussion
Best, I'm not sure, but a pretty effective technique that works well both server and client side is to seperate a logical URI path from a physical (URL) version path. In the physical realm I would keep as seperate yaml versions.
- /v2/users/{id}
- /v1/users/{id}
On top of that provide logical URI paths, where I've used current or latest, use naming consistent with your organisation norms, so these might be live, staging or whatever makes sense to your peers.
- /current/users/{id} - the current live version
- /latest/users/{id} - might be the overnight build
- /legacy/users/{id} - the previous version
I typically prefix the API with its unique identifier/name even if that would be currently redundant.
- /sso/current/users/{id} -> /sso/v2/users ...
- /sso/latest/users/{id} -> /sso/v3/users ...
- /sso/legacy/users/{id} -> /sso/v1/users ...
