Compatibility with API v3 and v4

[connorshea]

Rather than making a new major version of the gitlab gem for GitLab 9.0 (and the GitLab API v4), could we make the gem compatible with both v3 and v4 simultaneously?

Something like the following?:

def create_fork(id, options={})
  if (Gitlab.api_version == 4) {
    post("/projects/#{id}/fork", body: options)
  } else {
    post("/projects/fork/#{id}", body: options)
  }
end

Then we can remove support for v3 in the future, after a few releases of GitLab 9.x. We'd also have to require users to specify the api version somehow.

Related: #235

[asedge]

I worry about how ugly this could get as the API versions further diverge.

[connorshea]

True, I'm not sure how this would best be handled to prevent a complete mess of technical debt. Maybe remove the v3 endpoints after official support for 8.x is dropped with the release of 9.3?

[asedge]

Do you know when that will be? I've been holding off the 4.0.0 release until we figure something out here. Being that my time is pretty limited I'm not sure I could commit to supporting both v3 and v4, so a hard cut doesn't sound like a bad idea.

[connorshea]

9.0 is currently scheduled for February 2017, might end up being later than that but definitely no earlier.

[asedge]

That's a little far out to hold off version 4 of this gem. Any more thoughts on supporting both versions?

Inheritance keeps popping into my head but the idea of duplicating every module under lib/gitlab/client also bothers me.

What if instead create_fork could ask another object for the route it's supposed to use to make its call?

def create_fork(id, options={})
    post(Gitlab::Client.routes.create_fork.post, body: options)
end

Then Gitlab::Client (or whatever really) would be the only thing that needed to know what version of the API you were calling and how to provide the correct route when asked. Then we would just need a couple of config files that contained the correct routes for each version and read them (unsure of actual implementation details - not totally enamoured with this detail):

--- # v3.yml
create_fork:
  post: "/projects/fork/#{id}"

--- # v4.yml
create_fork:
  post: "/projects/#{id}/fork"

I guess the best way not to duplicate the same route in both files would be to load them in alphabetical order until you hit the correct version, so that routes defined in v4.yml could override the same in v3.yml. Thinking down the road a bit we would probably need to trigger a reload of the files if someone changes their api version (via endpoint=).

There's probably a better implementation than the one I just outlined, but I think the overall idea might be the cleanest and simplest to implement. Thoughts? @connorshea, @jvanbaarsen, or anyone else with an opinion or better idea?

[brodock]

May I suggest a different approach?

The way versions are handled on the server side (with Grape), is by mounting namespaces. If the idea is to have both V3 and V4 supported, the best would be to namespace everything with V3 and V4 and whenever the change is simpler, just inherit the classes and change whatever is different, and when diversion is big enough, build a brand new class.

You can programmatically "refine/extend" the client with one or the other based on the supplied API version number.

[asedge]

@brodock Could you provide an example?

Honestly, I'd rather not support both V3 and V4 going forward. When we first discussed this last year a February release for Gitlab 9 was a ways off. I was trying to figure out how to satisfy the people asking for a new release of this gem - which is a major version bump based on the deprecation of Ruby < 2.0. Dropping support for V3, in my eyes, is also a major version bump. If we could have come up with a solid plan for supporting both versions then it was less of an issue to push 4.0.0 to RubyGems.

[asedge]

I have decided that starting with release 4.0.0 of this gem, which will be coming soon, we will only officially support V4 of the Gitlab API.