Net API Notes for 2020-01-09 - Issue 118

A quick snowstorm in the Northern Virginia area Tuesday (with the knock-on effects Wednesday) threw my publishing schedule off. Before we get any closer to the weekend, let's get to the notes!



Breaking clients because of an API design change is a big deal. However, creating a design forever unperturbed by the machinations of weather and wear is unrealistic. To create more long-lasting designs, Stephen Mizell has proposed the Graphable JSON specification.

The Graphable JSON specification defines additional constraints to apply to a JSON payload. This include:

  • Treating properties as relationships (assume any single value may eventually be a collection of values, and model it from the get-go as an array)
  • Convert values into links (if you are defining a hierarchical object in the response, push it to its resource and link to it, thus "flattening" most resource responses)
  • Avoid breaking changes via a value's data type by versioning at the property level (or clients can request different versions of different objects within the same API; if no version is given the original, oldest supported version is returned)

In the course of a given year, my team looks at thousands of OpenAPI descriptions. Curious, I asked them what causes the majority of breaking changes that we see. The results were interesting. Changes in object structure indeed happen. Changes to the data type or going from having to express one-value-to-many much less so; hopefully, I will only ever have one birth date, or social security number, or hummable John Tesh song within recall.

What we see most often, instead, is when the teams need to change the property name itself. This is most often to align terminology across domains for better comprehension. Based on our experience, getting to a shared language across internal producers and consumers is hella hard. Unfortunately, I don't see anything in Stephen's proposal that would help with that. And that would come with significant code complexity increase due to the the per-property versioning.

I love folks are thinking about this. Stephen's draft is a laudable start, and not just because the documentation is clean and well written. By accounting for additional reasons breaking changes occur, this specification might become something more broadly applicable.


Speaking of breaking changes, in mid-December, Tom Newton discussed how Shopify manages API Versioning and Breaking Changes.

A breaking change in the Spotify API means that tens of thousands of partners can no longer run their businesses. Creating a stable and predictable design is paramount.

Shopify lists the following reasons why a change may be breaking:

  • adding a new or modifying an existing validation to an existing resource
  • requiring a parameter that wasn’t required before
  • changing existing error response codes/messages
  • modifying the expected payload of webhooks and async callbacks
  • changing the data type of an existing field (as we discussed, above)
  • changing supported filtering on existing endpoints
  • renaming a field or endpoint (what I noted was a common occurrence in our neck of the woods)
  • adding a new feature that will change the meaning of a field
  • removing an existing field or endpoint
  • changing the URL structure of an existing endpoint

What's very impressive is the amount of support Shopify claims they've built into their deployment process. From new values being tagged to annotated values reflected in subsequent production reporting, it is impressive to see this level of rigor applied to ongoing design management.


However, there's more to life than just versioning. I wanted to give a shoutout to Ian Cooper's talk from last year entitled "Event Driven Collaboration". I went into it expecting a "soft skills" lecture. What I found, instead, was a wonderful dissection of SOA's good parts (yes, there are some), how they manifested within microservices, and when to drop the microservices in favor of event-driven architectures.


WRAPPING UP is the site for in-person API gatherings held around the world. Drop-in and get involved with your local community. If you're in the DC area on February 4th, I'll be presenting "Why AI Success is Built on APIs", the talk that was postponed due to the aforementioned snowstorm.

If you know of a meetup, hackathon, or conference that isn't there but should be, let me know by replying to this message.

Finally, thank you to the Patreons who continue to support this work.

Till next time,

Matthew @libel_vox and

Subscribe to Net API Notes

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.