REST API Notes for 2018-07-06

Howdy, howdy! I hope folks in the states had a happy and safe Fourth of July. And, for those everywhere else, I hope it was an unusually enjoyable Wednesday. Let's get to selected works for this week.



Stories about how governments wrestle with IT change aren't new. But this piece, by Terence Lee, has more depth than the usual 'aw-shucks-technology-struggles-with-bureaucracy' angle.

Astute readers may recognize aspects of the "Backends for Frontends" (or, as Daniel Jacobson calls them, "Experience Layers") architectural pattern. Chan Cheow Hoe, the government chief information officer, refers to this as a "whole-government API".

Toward the end, there also a nice mention of a phenomenon I've picked up on while attending the DC API Meetup Group: it's not that government agencies withhold data. It is actually quite the opposite. But the jumble of formats and lack of consistent interface often doom data sharing efforts to all but the most determined. An API approach, even if only exposing data to be read, is an important first step (see the first bullet under milestones, below).


Tareq Abedrabbo, in his article, discusses the concept of 'Entity Services' in relation to microservices. He explains what they are, and then outlines the differences between those services that result in simpler systems and those that increase overall complexity.

Complexity, on its own, isn't automatically a bad thing. Some problems require a complex solution. But, simple solutions tend to drift toward complexity over time. That complexity is then projected outward, requiring additional time and effort from the consuming team.

I've often referred to this as an 'over-granualized' decomposition. However, Tareq's concept of shallow modules do a better job of illustrating the problem. A great read.


The great and powerful Z recently resurfaced a great piece from Twilio's blog. Despite being five years old (practically the Cretaceous era, in internet years), 'How to Build HTTP Clients' still holds up. It offers up a copious amount of excellent advice in how to connect to API services.

With that in the brain pan, also check out Gennady Chibisov's cautionary tale. It describes a fictional(?) series of seemingly pragmatic choices for a web service retry that aggregate into... something else.


  • Twitterrific has a write up on how Twitter API changes have impacted them. Twitter has removed the live-streaming service for third-party apps and reduced the number of transactions per second allowed to the API (unless integrations opt for a higher paid tier). The effect is that 3rd party apps will be less "real time". It also crystallizes Twitter's ad, rather than platform, business strategy.
  • Oh hey! The UK Parliament has a OpenAPI 3.0 description! A quick pitstop at Nicolas Bonnel's OpenAPI Viewer shows, unfortunately, that its only GET requests (click the drop down arrow - the panel doesn't load by default). If you're tired of the Pet Store example JSON, this may not be an alternative to kick the tires when trying various OpenAPI tools. But hey, have to start somewhere, right?
  • JSON-LD Work Group has been formed. As you might know, the 'LD' stands for Linked Data and is the recommended format by The working group, co-chaired by the delightful Benjaming Young, will update the the JSON-LD 1.0 specification "to address specific usability or technical issues". This non-stop party bus don't stop until the expected end date of June, 2020.
  • You can run and test Postman collections from the command line. The feature, called Newman, allows collections to be integrated with a CI/CD pipeline, kicked off each time the build process is started.
  • CommitStrip is back with another great, API-related comic. I look forward to everyone's "Chatbot for Blockchain Smart Contracts Using GraphQL" talks this fall conference season.


I recently did some slight tweaks under the hood to It remains a great source for upcoming, in-person Web API gatherings around the globe. It also is served over http, not https. Tsk, tsk. I plan on making that, along with a visual refresh, a fun project for my oldest son and I this month.

Also, thanks for folks that had questions about my Patreon page. If you have enjoyed the updates, I've made it a bit easier to tip a coffee (or two) for those late nights and early mornings (I think about this Amanda Palmer TED Talk a lot.)

Thanks for reading. Till next time,

@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.