Net API Notes for 2019/10/03

One whirlwind, mid-week trip to New York City, and it is time, again, to post another Net API Notes.



GraphQL has been in the public conversation long enough that we're now seeing interesting, multi-year observations of what worked and what didn't. Jon Wong is the latest and talks about his experience using GraphQL while at Coursera in "Evolving the Graph".

In a REST-ish or net API, the decision to go code-first or design-first isn't apparent. Both ways come with pros and cons. With GraphQL, there are similar tradeoffs. Coursera initially chose to go code-first rather than design a Schema Definition Language document (or SDL). Fast forward a few years, and:

From a technical standpoint, it was really simple to get new things into the GraphQL schema, but we never really had a strong opinion about whether these new things should be in the schema in the first place. Again, given the context of the project, this explicitly wasn’t a goal, but after three years of unbounded growth, our GraphQL schema was bursting at the seams: We have more than 7,000 types, and more than 650 root types. One of the benefits of GraphQL is discoverability, but with so many entities, it was really difficult to figure out which APIs existed already, and without proper governance of the schema, these APIs were not particularly well documented, either.

There's more great nuance throughout the rest of the piece. However, I found the switch to a schema-design-first over data-first approach, even when dealing with a GraphQL API, enlightening.


This article, by Gwen Shapria, came out earlier this year. However, "Schemas, Contracts, and Compatibility" is one of the best high-level overviews of event-streaming microservices that I have seen.

There are lots of ways for services to talk with each other. Many of us default to using HTTP, as that is what we're most familiar with, have the infrastructure to support, etc. However, assuming that inter-service communication must be HTTP driven bypasses a beneficial, real-time architectural solution. Check it out.


Speaking of HTTP, we should talk about the latest, greatest making its way onto the web as I type. I know that HTTP/2 support is not yet ubiquitous within many API environments. This is even though it offers potential speed increases.

But good news! If you have yet to take advantage of HTTP/2, you can skip a generation and go directly to HTTP/3!

I'm joking (mostly). However, folks should, at a minimum, have a high-level understanding of what the new protocol offers. For a quick primer, I'd recommend Jesus M Gonzalez-Barahona's recent tweet stream. If you are interested in more after that tidbit, check out Daniel Stenberg's more in-depth presentation on YouTube. Then ask your middleware vendor for an ETA.



Want more API conversation while you're out and about? Check out There's still plenty more upcoming opportunities to get together with your local community.

Further, if you know of a meetup, hackathon, or conference that is missing, let me know. I'd be happy to add it.

Also, a big thank you goes out to my Patreons. I've been thinking about doing a "This Old House" write-up for those folks, except for APIs; identify a useful, but problematic, net API (Wikipedia, I'm looking at you), identify the trouble spots, and then build up a theoretical design that is more intuitive, accommodating, and fitter than the original. Would anybody find this kind of real-world design exercise useful? If so, let me know.

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.