Showing results for 
Search instead for 
Did you mean: 

What is the best way to version paths?

New Contributor

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 paths. I want to be able to say that the new path has a new version (/v2/users/{id}) while still maintaining the old version (/v1/users/{id}) without having to name the path with "/v1" and "/v2" in the path. If I have to do that, I would probably not maintain both paths in the same yaml file. I would probably just have a different version of the yaml. 

What are some techniques that people are using to manage their API versions?


Frequent Contributor

Re: What is the best way to version paths?

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 ...