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

i've been reading on versioning strategies rest apis, , none of them appear address how manage underlying codebase.

let's we're making bunch of breaking changes api - example, changing our customer resource returns separate forename , surname fields instead of single name field. (for example, i'll use url versioning solution since it's easy understand concepts involved, question equally applicable content negotiation or custom http headers)

we have endpoint @ http://api.mycompany.com/v1/customers/{id}, , incompatible endpoint @ http://api.mycompany.com/v2/customers/{id}. still releasing bugfixes , security updates v1 api, new feature development focusing on v2. how write, test , deploy changes our api server? can see @ least 2 solutions:

• use source control branch/tag v1 codebase. v1 , v2 developed, , deployed independently, revision control merges used necessary apply same bugfix both versions - similar how you'd manage codebases native apps when developing major new version whilst still supporting previous version.

• make codebase aware of api versions, end single codebase includes both v1 customer representation , v2 customer representation. treat versioning part of solution architecture instead of deployment issue - using combination of namespaces , routing make sure requests handled correct version.

the obvious advantage of branch model it's trivial delete old api versions - stop deploying appropriate branch/tag - if you're running several versions, end convoluted branch structure , deployment pipeline. "unified codebase" model avoids problem, (i think?) make harder remove deprecated resources , endpoints codebase when they're no longer required. know subjective since there's unlikely simple correct answer, i'm curious understand how organisations maintain complex apis across multiple versions solving problem.

i've used both of strategies mention. of two, favor second approach, being simpler, in use cases support it. is, if versioning needs simple, go simpler software design:

• a low number of changes, low complexity changes, or low frequency change schedule
• changes largely orthogonal rest of codebase: public api can exist peacefully rest of stack without requiring "excessive" (for whatever definition of of term choose adopt) branching in code

i did not find overly difficult remove deprecated versions using model:

• good test coverage meant ripping out retired api , associated backing code ensured no (well, minimal) regressions
• good naming strategy (api-versioned package names, or uglier, api versions in method names) made easy locate relevant code
• cross-cutting concerns harder; modifications core backend systems support multiple apis have weighed. @ point, cost of versioning backend (see comment on "excessive" above) outweighs benefit of single codebase.

the first approach simpler standpoint of reducing conflict between co-existing versions, overhead of maintaining separate systems tended outweigh benefit of reducing version conflict. said, dead simple stand new public api stack , start iterating on separate api branch. of course, generational loss set in immediately, , branches turned mess of merges, merge conflict resolutions, , other such fun.

a third approach @ architectural layer: adopt variant of facade pattern, , abstract apis public facing, versioned layers talks appropriate facade instance, in turn talks backend via own set of apis. facade (i used adapter in previous project) becomes own package, self-contained , testable, , allows migrate frontend apis independently of backend, , of each other.

this work if api versions tend expose same kinds of resources, different structural representations, in fullname/forename/surname example. gets harder if start relying on different backend computations, in, "my backend service has returned incorrectly calculated compound interest has been exposed in public api v1. our customers have patched incorrect behavior. therefore, cannot update computation in backend , have apply until v2. therefore need fork our interest calculation code." luckily, tend infrequent: practically speaking, consumers of restful apis favor accurate resource representations on bug-for-bug backwards compatibility, amongst non-breaking changes on theoretically idempotent getted resource.

i'll interested hear eventual decision.