Heads up: API v2

[ianrandmckenzie]

Hello,

I got an email saying that the API is being upgraded:

Today we are contacting anyone with an account to announce a new version of the Oxford Dictionaries API will be released in April.

Oxford Dictionaries API v2 represents a major improvement to the API and its underlying data platform. While minimizing the impact on the user experience we have made important changes that will make the API v2 more consistent, flexible, and more powerful for your use in the future.

Oxford Dictionaries API v2 will be released Tuesday 16 April 2019. A migration guide will be made available to you for this transition, and we will be updating and replacing our documentation.

We will shut down the API v1 on Sunday 30 June 2019. After this date any applications that are still using v1 will no longer work. You should plan to migrate your applications to v2 as soon as possible after it is released.

We look forward to sharing v2 with you and will be in touch with information and migration resources in April.

Is this something that this gem maintainers will be supporting once it is released? Do you need assistance upgrading?

[swcraig]

Hi @ianrandmckenzie,

Thanks for the heads up!

I would plan on supporting this once it is released. Dependent on the new API structure I should be fine, but I can keep you posted if you are interested in contributing.

[elifoster]

It's been released. Here's the migration guide.

[ianrandmckenzie]

Hey @swcraig,

I got an email from Oxford today reminding us that API V1 shuts down in 30 days. Do you need help with the migration before V1 gets shut down? I have 3 apps that rely on this wrapper and need to know if I should fork it this month.

Thank you for your time.

[swcraig]

Hey @ianrandmckenzie,

I'm am putting time into the migration this weekend. If I don't make good progress (or suspect that I won't be done in time to allow users to switch/test before the shut down) I will notify in this thread. I understand this is a relatively tight timeline.

[swcraig]

Hi @ianrandmckenzie,

I've got a decent start at the upgrade on this branch. I'm travelling for work this week but will aim to have the new version up next weekend.

If you aren't comfortable with that, feel free to fork. Otherwise if you'd like to contribute to this repository you could take a look at adding some codes for any of the Thesaurus, Sentence, Translation, and Search endpoints specifically. In the v2 API those required a paid plan (which I do not have); I am only able to dev "live" on the Entries and Lemmas endpoint. My plan for the other four endpoints was to code against the docs, and then get the community (most likely you) to validate correctness.

If you want to talk more about this, or specific implementation details, please feel free to send me an email (or open new issues).

[ianrandmckenzie]

Thanks, @swcraig that's wonderful. I am actually on the free plan as well since all I use are Entries, but there are some months where I'm teetering on the free limits, so I'd be happy to contribute to the paid endpoints once I pass the threshold into the paid tier.

I am perfectly comfortable with you getting things taken care of this weekend. That should give me plenty of time to test next week. The timing is actually really good, I just wrapped up a major project this week and have a nice opening of time for testing this.

[swcraig]

I've cut 1.1.0 (which contains support for the Entries endpoint).

Here is the PR to reference for the new interface.

I'll release more of the endpoints in future minor versions, but this should be enough to upgrade Entries to V2.

[swcraig]

OK Folks,

I've cut v.1.3.0 which includes both the free and paid tier endpoints. Please check that PR for some more information on how/where to find information on upgrading applications that use this library.

As mentioned, the PRs relevant for the new V2 interfaces are as follows:

• Entries: Add OxfordDictionary::Endpoints::Entries #8
  • I added more deprecations related to this endpoint here
• Translations: Add OxfordDictionary::Endpoints::Translations #12
• Sentences: Add OxfordDictionary::Endpoints::Sentences #13
• Thesaurus: Add OxfordDictionary::Endpoints::Thesaurus #14
• Lemmas: Add OxfordDictionary::Endpoints::Lemmas #10
• Search: Add OxfordDictionary::Endpoints::Search #15

v2.0.0 of this library (which I will cut later this week) will include the removal of all V1 interfaces.

As noted, I wasn't entirely on the ball upgrading this in a timely fashion (my apologies) but something something Parkinson's Law.

Seeing as there is only a week until Oxford Dictionaries discontinues V1, if anything looks off, please open issues/PRs and I will get to them before that date.

[ianrandmckenzie]

@swcraig looks great! I updated to 1.3.0 and all of the Oxford components of my app passed automated and manual tests with flying colors :)

[swcraig]

Great to hear.

I've released v2.0.0 which has removed all of the calls to the V1 endpoints. The V2 interface (with named parameters) is documented in the README and the aforementioned PRs that added the new endpoints. I plan on removing the deprecated interfaces (without named parameters) in v3.0.0.

[swcraig]

Hi Folks,

I've released v3.0. This entirely removes all V1 interfaces.

With 3.0 out I'm closing this issue. Thank you both @ianrandmckenzie and @elifoster for the notice and migration link.

Have a great weekend.