Forum Discussion

jasonkilgrow's avatar
jasonkilgrow
New Contributor
6 years ago

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?

Thanks! 

  • MartinSpamer's avatar
    MartinSpamer
    Frequent Contributor
    6 years ago

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