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!

NOTES

GRAPHABLE JSON TO SUPPORT API DESIGN CHANGES

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.

SHOPIFY ON BREAKING CHANGES

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.

SOA, MICROSERVICES, AND EVENT-DRIVEN ARCHITECTURES

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.

MILESTONES

• Are you reading APISecurity.io? It is a regular, deep dive into how APIs can fail (and what can be done about it). In short, violation of OWASP API3:2019 (excessive data exposure) seems to be a common sin.
• APIMetrics launched API.expert, a site for monitoring performance for a number of notable cloud providers. Their "Cloud API Service Consistency" score is a black box, unlike Apdex. Also, speaking from experience having been on the wrong side of the line when reporting to executive leadership, there's a difference between actionable data and infopr0n. It will be interesting to see where this goes.
• There's another version of the HTTP Deprecation header field. Erik Wilde describes how best to use it over on the GoodAPI.co site.
• JSON-LD, a method for adding linked data to JSON, has now reached 1.1 candidate status.
• It's official! OpenAPI's 3.1 Schema Object will now be legit JSON Schema! TBH, I'm not sure how this impacts my day-to-day, but if Phil Sturgeon is happy, I'm moderately less unhappy!

WRAPPING UP

NetAPI.events 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 matthewreinbold.com