I&#39;ve been reading up on versioning strategies for ReST APIs, and something none of them appear to address is how you manage the underlying codebase.

Let&#39;s say we&#39;re making a bunch of breaking changes to an API - for example, changing our Customer resource so that it returns separate `forename` and `surname` fields instead of a single `name` field. (For this example, I&#39;ll use the URL versioning solution since it&#39;s easy to understand the concepts involved, but the question is equally applicable to content negotiation or custom HTTP headers)

We now have an endpoint at `http://api.mycompany.com/v1/customers/{id}`, and another incompatible endpoint at `http://api.mycompany.com/v2/customers/{id}`. We are still releasing bugfixes and security updates to the v1 API, but new feature development is now all focusing on v2. How do we write, test and deploy changes to our API server? I can see at least two solutions:

- Use a source control branch/tag for the v1 codebase. v1 and v2 are developed, and deployed independently, with revision control merges used as necessary to apply the same bugfix to both versions - similar to how you&#39;d manage codebases for native apps when developing a major new version whilst still supporting the previous version. 

- Make the codebase itself aware of the API versions, so you end up with a single codebase that includes both the v1 customer representation and the v2 customer representation. Treat versioning as part of your solution architecture instead of a deployment issue - probably using some combination of namespaces and routing to make sure requests are handled by the correct version.

The obvious advantage of the branch model is that it&#39;s trivial to delete old API versions - just stop deploying the appropriate branch/tag - but if you&#39;re running several versions, you could end up with a really convoluted branch structure and deployment pipeline. The &quot;unified codebase&quot; model avoids this problem, but (I think?) would make it much harder to remove deprecated resources and endpoints from the codebase when they&#39;re no longer required. I know this is probably subjective since there&#39;s unlikely to be a simple correct answer, but I&#39;m curious to understand how organisations who maintain complex APIs across multiple versions are solving this problem. 





All Api Versioning Solutions on Gang of Coders

Total of 1 Api Versioning Solutions

How do you manage the underlying codebase for a versioned API?