API Backwards Compatibility

[Illyism]

Hi all,

I finished part of the MagicSpace Programmatic SEO Course login using the Polar API. But once deployed yesterday I noticed that polar.users.licenseKeys.validate stopped working and was throwing a zod error.

This is because, once I updated to "@polar-sh/sdk": "^0.18.1", I noticed that the users SDK was deleted and moved to customerPortal.

I think there are two issues here:

1. Breaking API changes should have a Semver major version upgrade.
2. Changes on the API side should be backwards compatible and not break stuff in production.
3. Breaking API changes like this should be notified to developers by email (you can check who has PATs set / oAuth enabled)

It's hard for me to know when / if you decide to change around the API. And I can't trust that it won't break for my customers. This is very important.

[frankie567]

Hello @Illyism 👋

I'm François, software engineer at Polar and the main culprit for this issue 😊 We deployed a big change yesterday to our system, that indeed changed a lot of endpoints and schema. I tried to make it backward compatible (e.g there or there), but I didn't foresee Zod schema would be so picky.

That's why I thought a notice + major semver upgrade wouldn't be necessary in this case. I'm really sorry about that.

So here is the plan to fix the situation:

• Fix our OpenAPI schema so it's truly backward compatible with SDK 0.18.0
• Publish SDK with updated API under the 0.19.0 version
• Add depreciation warning to 0.18.1

---

Once this done, you'll have two solutions:

• Rollback to SDK 0.18.0 and keep your code untouched
• Upgrade to 0.19.0 and update the method call (should be polar.customerPortal.licenseKeys.validate)

---

I'll keep you updated about the progress of all this. We'll make sure this doesn't happen again in the future 😊

[Illyism]

Hey @frankie567!

I'd probably not unpublish SDK 0.18.1 since I'm using it now :)

I already shipped the customerPortal changes!

So for me, this is not an issue anymore - but something to think about for next time!

[frankie567]

Ok, let's keep it then 😄 Thank you for your feedback 🙏

[frankie567]

Ok, all done on this :) I've verified that SDK 0.18.0 work properly with the current API.

I've issued a depreciation warning on 0.18.1:

You should be safe to upgrade to 0.19.0 without any change.

Thank you for your trust 🙏