Cloud API: breaking changes without version bump?

Cloud
1

Hi, it seems like the Cloud API endpoint for “product detail” just changed recently (not sure how recently exactly), and this has happened without a version bump, and seemingly without any warning.

Specifically, the /v1/products/:id endpoint response format has changed. 2 major changes:

  1. The payload at $.product is now a hash/object, rather than an array
  2. A bunch of the attributes of that product object are different.

Full before/after diff is below.

This is problematic because it randomly breaks functionality for clients/customers/users of Particle. For example, we have a custom build script that builds new firmware, uploads it, pings our system, and does some other stuff. This requires getting some information about the product we’re building for. This recent API change broke that script and set off a fair bit of debugging.

Note: I feel like a Github issue would be the ideal place to put this, but I don’t think the API code is open-source, and I wanted to let someone at the Particle team know about this issue, and suggest changes; and also to see if there are some update channels that we should be aware of where we can be notified of changes.

My recommendation: use (actually use) semantic versioning. So this new endpoint format would work just fine at /v2/products/:id.

Example of what changed:

Old response body format (from the current docs, which reflected the truth until recently):

{
  "product": [
      {
          "id": "0123456789abcdef01234567",
          "product_id": 6,
          "name": "Photon",
          "slug": "photon",
          "description": "Traveling Light",
          "type": "Consumer",
          "hardware_version": "v1.0.0",
          "config_id": "0123456789abcdef01234567",
          "organization": "0123456789abcdef01234567",
          "platform_id": 6,
          "requires_activation_codes": false
      }
  ]
}

New response body format:

{
  "product": {
    "id": 12345,
    "platform_id": 10,
    "name": "myproduct",
    "slug": "myproduct-v010",
    "description": "This is a super cool product whose description I have changed",
    "subscription_id": 11111,
    "mb_limit": null,
    "groups": [],
    "settings": {
      "quarantine": true
    },
    "org": "myproduct-v010"
  }
}

Would like to know if there can be some commitment to semantic versioning. Thanks!

2

Hi TyGuy,

You are correct, we did make this breaking change in the API response for that endpoint. We’d like to apologize that caused breakage for your app. Our (wrong) assumption was that this endpoint was only used by Particle Console as we did not detect traffic, at the time, for that endpoint outside of Console requests so we changed the response format without proper semantic versioning handling.

We are working on a major change on how we handle products and organizations and part of that process involves changing / adding or modifying existing endpoints. We will make sure that any other breaking changes will be announced and properly versioned.

Since you seem to have already adapted your app for the new response (thank you) and we haven’t received additional reports about this issue it wouldn’t make sense to roll this change back or change the API version it at this point. Thanks for pointing out that the documentation no longer reflects reality. We’ll get that updated.

Again, apologies. If you have additional concerns please let us know

Julien, Director of Engineering @ Particle

3

Hi @jvanier, thanks for the response.

We build our firmware with these scripts anywhere from once every few days to once every few weeks; so it makes sense that the traffic you’d see would be very low. Agreed that if it’s not affecting anyone else, it doesn’t make sense to roll back.

Sounds good on the documentation update, and we appreciate the commitment to semantic versioning in the future.

No additional concerns; thanks for getting back to me.

4

I also would like to check if a breaking change may have broke our app. We use this endpoint to create customers with a secure random hash as the user ID. The endpoint we would use is: https://api.particle.io/v1/products/PRODUCT_ID/customers. It seems that the API now expects an email address formatted identifier which used to not be the case. Can I confirm that Particle has changed this behavior and is now enforcing email addresses as customer identifiers? @jvanier

I should add that this changed caused some orders to not go through and are now unrecoverable resulting in thousands of unrecoverable lost dollars. I agree that breaking changes need to be announced and please let us know where to find these announcements.

Original conversation: Particle Customer Email

5

The create customer API endpoint was documented as taking an email address. The implementation was meant to validate email addresses but was not properly returning an error for invalid emails. We were not aware of this conversation from 2017 or that people were depending on the undocumented behavior of providing an invalid email so we didn’t consider fixing the email validation bug a breaking change.

I’ll discuss internally with the team but it sounds like we should remove the email validation and document that passing a unique ID instead of a valid email when creating a customer is OK.

6

I completely understand that maybe we were using a non-standard implementation. I’ve already fixed this so that we are now passing ‘email address like’ identifiers so it is not really an issue for us anymore, not sure if this is an issue for others. But these aren’t really valid email addresses that we are using now, they just look like email address. Maybe Particle decides that the user needs to click a confirm link in the future and all a sudden we have even bigger issues. For this reason I am really concerned about future changes and how I am to be aware that they are being made. Where are upcoming changes announced so we know if it is going to break something?

7

The change for email validation has been reverted and the API documentation clarified that it’s possible to pass an identifier that is not an email, but then some platform functionality won’t work.

Before we make changes that might affect specific product creators we will reach out directly by email to notify them. In addition we’ll post on the community forum before rolling out those changes.

8

Thank you for the prompt responses and for being clear about actions being taken. I appreciate it.