4

If I was to create a versioned RESTful API in .NET (it doesn't matter on the way I'm versioning, but for the sake of argument lets say i'm doing api/v1/users) - I'm interested in how people deal with this in respect to version control and code. In my situation it's a private API, however it will be used by iOS Apps, so I can't guarantee all the clients will upgrade at the same time, so I'll have to keep the old API's running for a time.

So say I've decided to implement a breaking change in the data that Users returns, so I create a v2 of the api - api/v2/users. Do I do these changes in GIT, so for example, create a new branch for V2 and then make those changes on top of the working copy, and then build each branch separately and deploy each branch project to a v2 folder

Like:

/branchV1/user.cs -> Built by Jenkins -> Deployed to V1/user
/branchV2/user.cs -> Built by Jenkins -> Deployed to V2/user

And the Git branching:

MASTER ====v1========================v2==========================
            \               \          \
             \               \         BRANCH V2 =================
              BRANCH V1 ===========================================
                                            \                     /
                                             BRANCH V1 Bug Fix ===

Obviously this brings an overhead of having to add each branch to Jenkins when creating it, and then updating the Deploy procedure on AWS to install the relevant WebDeploy packages in the right places. In this situation as well, the MASTER would be not constantly shippable, it would be Dev, the constantly shippable versions would be the Branches

Or do people just have on project with the differing versions, so for example v1/Users.cs v2/Users.cs - with different namespaces and then deal in code to which that gets routed to.

The latter is much simpler to deal with, as there's just one project to deploy to the front end at any one point. However it feels messy to me, and out of the core values of code versioning.

I've seen a lot of discussion about URL naming vs Header naming etc for REST Versioning, but nothing on how people implement versioning in their code base, and version control.

Thanks folks

Brett Jenkins
  • 192
  • 2
  • 9
  • 1
    Have you checked http://nvie.com/posts/a-successful-git-branching-model/ ? Perhaps this can give you different ideas for your problem. I personally dont like to deliver from branches, but instead, have Jenkins to build for any branch non-master, and them promote something to production. Hope this can be somehow helpful. – Lovato Sep 04 '14 at 13:35
  • Thanks for that comment Lovato, it helps :) My only problem with something like that, is how would Jenkins know which version it is and where it's going - ie if I release v3 but only on the trunk, Jenkins wouldn't know it should be under /v3/ - if I did it under a branch at least I could tell Jenkins what each branch means. I don't know :/ – Brett Jenkins Sep 04 '14 at 13:48
  • Perhaps you can try to give meaning to versioning, like 1.2.3.4. Twitter does that, and inspired me. Twitter API is 1.1. Period. But internally, it may be something 1.1.244, which means its revision 244 since it was released (can use also build_version from jenkins). Then, you can parse your product version on Jenkins, on a pre-build step. If you use gitlab/github, and WebHooks, it sends a payload with all the details about what was pushed, so you can checkout the branch you want, do whatever you want, build and deploy. – Lovato Sep 04 '14 at 13:56
  • That said, you get changed branch, get current version, increment last digit, commit back (be aware to not trigger jenkins again) and properly deploy it. – Lovato Sep 04 '14 at 13:58
  • Also it would be good if you have a look at this post: http://stackoverflow.com/questions/972226/how-to-version-rest-uris – MHOOS Sep 05 '14 at 11:28

1 Answers1

0

In my opinion you have 2 choices:

  • Fork v1 and create a separate project for v2. In this case you can copy-paste the bugfix, or maybe it is possible to share the fix with a pull request.
  • Create separate release branches for v1 and v2 and so you can merge the bugfix to both of them.
inf3rno
  • 24,976
  • 11
  • 115
  • 197