Cloud API Changelog?

Is there a changelog for cloud API changes, or something similar one could subscribe to to get breaking changes? I received a call from a customer on the field after the endpoint for creating customer access tokens changed from ‘/v1/orgs/orgSlug/customers’ to ‘/v1/products/productId/customers’, which prevented him from claiming a product through our app.

There is no API changelog, however we are very strict about not making breaking changes. I’ve been in plenty of meetings where someone proposes a really great change, but someone points out it would break existing implementations, and so we work to accomplish the same goal a different way.

At some point, perhaps next year, we’ll release API v2 which will be completely different. We’ll make all our breaking changes at one go. You’ll be able to continue to use API v1, but we’ll stop development on it.

Regarding the “create customer” endpoint, AFAIK the org version still works, we just stopped advertising it. Using the product customer endpoint will ensure the best experience across all our tools, but I don’t believe it actually broke. If I’m wrong, please don’t hesitate to let me know.

3 Likes

@zachary sounds good.
I guess I should correct my previous statement: I was using ‘v1/orgs/productId/customers’, not ‘v1/orgs/orgSlug/customers’. Maybe ‘orgs’ is not compatible with ‘productId’? I can explain how I got there.
In one case a while back, I was using /v1/products/myOrgSlug/devices?deviceId= to get the details of a particular device and verify it belongs to a specific customer. I noticed it later stopped working when running internal tests. I solved it by changing to /v1/products/myProductId/devices?deviceId=.
To create a customer access token, I was originally using ‘v1/orgs/myOrgSlug/customers’. I then changed it to ‘v1/orgs/productId/customers’ when I made the change in the paragraph above above, but I may not have tested it (bad practice of me, I know). After getting the customer call, I saw I was getting I was getting a 404 with { “error” : { “S” : “Organization not found.” }, “ok” : { “BOOL” : false }} in the body. I changed it to ‘/v1/products/productId/customers’ and that worked.

1 Like