Gibbon::API.new is now Gibbon::Request.new

[DanielKehoe]

It looks like Gibbon 2.0.0 was released July 29, 2015.

In a number of applications, including several example applications from the RailsApps project, I initiated a new Gibbon instance with:

Gibbon::API.new(Rails.application.secrets.mailchimp_api_key)

It seems Gibbon 2.0 now requires:

Gibbon::Request.new(api_key: "your_api_key")

Is that correct?

I've got an application that recently was deployed with a bundle update and consequently uses the new Gibbon 2.0.0 and I am getting errors:

NameError: uninitialized constant Gibbon::API 

Just curious, why was it necessary to change the API? It's a big headache now to change all my apps to either lock the Gibbon version or change the code for the new version. Any chance of restoring the legacy method in a maintenance release?

Are there other breaking changes I haven't noticed yet? Could we have a cheatsheet listing the changes, please?

[amro]

Hi Daniel,

Yes, Gibbon's syntax has changed because Gibbon 2.x hit MailChimp API v3 and API v3 is very different from v2, which Gibbon 1.x targeted. It's true that initialization syntax could have stayed the same, but I decided to be explicit about what was passed in. I decided to change it now because it's a breaking change and the rest of the API needed to be changed to match the changes in MailChimp's API. Otherwise using Gibbon with MailChimp's new API would not be natural.

Sorry this has caused you trouble. I do two things to help folks avoid this sort of thing:

1. Gibbon subscribes to semantic versioning. This is common in the Ruby community. I suggest using the pessimistic operator in your gemfiles to specify the major/minor version your project works with. e.g.

gem 'gibbon',  '~>1.2.0'

In short, I only release breaking API changes with major version changes so it's easy for developers to manage dependencies.

2. A message is printed after installing Gibbon 2.x that explains the syntax has changed. I realize this is easy to miss.

Gibbon's README has been updated to reflect the syntax changes as well. And, of course, I'm happy to answer questions if you run into trouble trying to use Gibbon.

[DanielKehoe]

Thanks for the quick response. I appreciate the work you've done to build and maintain this gem. Thanks for explaining the need to change the API.

Any chance of adding a list to the README of the changes in v2.0? So I can compare the old and the new?

[amro]

My pleasure. The list is sort of "everything" but that's not very helpful. :) Would a few examples of moving syntax from the old version to the new version be helpful?

(By the way, the reason it's "everything" is because MailChimp's new API is restful and has nested resources. Gibbon builds URLs much differently from before to support this in [I think] a reasonable way.)

Edit: Grammar and clarification

[DanielKehoe]

Oh dear, "everything." Okay. How about a wiki document (or a README section) about upgrading from Gibbon 1.0 to Gibbon 2.0? With examples. Thanks :-)

I'll have to update the ‘Learn Ruby on Rails’ book which uses Gibbon, as well as several of the RailsApps example applications. Sux to be me :-)

[amro]

Oof. Sure thing! I'll do my best to add a decent README section sometime today. I'll post back here when I've done so.

If it helps, MailChimp has deprecated API version earlier than 3.0. Eventually (probably quite some time though I have no inside knowledge) API 2.0 will stop working.

[amro]

@DanielKehoe I've updated the README. Please let me know if you still have questions.

Edit: And by that I mean if there's something specific you think I should add.

[amro]

Closing this but let me know if the migration examples are not enough to get you started.