ryanuber
By:
ryanuber

API data structure changes break clients

January 26, 2015 2.1k views

On various occasions, I've noticed the data structures returned by the API (both v1 and v2) change in a backwards-incompatible way without notice. For example:

https://developers.digitalocean.com/changelog/api-v2/numbers/

The above change breaks existing clients that care about the data type returned. It also seems that the "regions" array has changed from []string to []int, and "region_slugs" now contains the string values for the regions.

It would be great if there was a stronger compatibility promise for existing API endpoints. Currently, even pinning to a specific API version does not guarantee client stability, and makes using DO with various open source tooling which expects certain things from the API responses unpredictable and frustrating.

5 comments
  • Hey Ryan,

    Sorry you've had some frustrations in this area. Right now our V2 API is still in BETA and changes such as the above are still happening as we want to make sure to get it right! We advertise this on the top of our developers page (https://developers.digitalocean.com/), but I apologize if it was not obvious. We have not purposely made changes to V1 and it has been stable for awhile. Please let me know if you found a change that occurred in the V1 API and I will look into it. V2 is coming pretty close to stable and the beta tag should be removed in the near future.

    If you have any other questions/problems please feel free to reach out to me at brooke(at)digitalocean.com.

    • Brooke McKim, Product Manager
  • Hi Brooke,

    Thanks for the reply. Understood about v2. Almost all of the problems we encounter are in v2. The v1 change that threw me was the addition of regions and region_slugs. According to the docs for v1, they weren't part of the original spec. However, at some point regions was added as []string. Later on, this seems to have changed to []int, and a secondary region_slugs added with the original []string value.

    I'm not sure if it was intentional to have these fields in /v1 or not, but if so, changing their types after introducing them into a stable API can be troublesome for clients.

  • I took a look at the response we return and it appears it hasn't changed since Feb 2014. It looks like we added both regions []int and region_slugs []string. You are correct that this is not documented and we will get that fixed up. However, I do not see anywhere the response was altered after it was introduced.

  • Hmm, odd. I don't have historical data about the API responses, so I'll chalk it up to our client for now. Thanks for the help, Brooke! I appreciate it.

  • It's happened to us too... I wish they would move to using api201.digitalocean.com or something that would allow users time to upgrade instead of breaking programs. I had even complained about it on a ticket but they didn't seem to be interested.

1 Answer

This question was answered by @brooke:

Hey Ryan,

Sorry you've had some frustrations in this area. Right now our V2 API is still in BETA and changes such as the above are still happening as we want to make sure to get it right! We advertise this on the top of our developers page (https://developers.digitalocean.com/), but I apologize if it was not obvious. We have not purposely made changes to V1 and it has been stable for awhile. Please let me know if you found a change that occurred in the V1 API and I will look into it. V2 is coming pretty close to stable and the beta tag should be removed in the near future.

If you have any other questions/problems please feel free to reach out to me at brooke(at)digitalocean.com.

  • Brooke McKim, Product Manager

View the original comment

Have another answer? Share your knowledge.