REST API Notes for 2018/10/29

Lordy, lordy. Yesterday folks woke to news that a behemoth largely regulated to history emerged from the deep, big blue ocean and consumed a megashark. Or IBM acquired Red Hat. The consolidation in the enterprise software space continues. More on that in a minute.

What also continues is another set of thought provoking pieces for busy practitioners. Let's get into the notes for this week.



I'll start, this week, with a piece from Chris Wood entitled "Making the Most of Your API Specification". For some, following an API-design-first approach may be something that they've done for years. For others, Chris's piece is a gentle onboarding as to why this stuff is important.


Daniel Lindau, writing on the Nordic API blog, has a great piece on the "8 Vital OAuth Flows and Powers". I'm always looking to find a new wrinkle or insight about OAuth, and this article is filled with them. It is a big recommend, particularly for those who have only ever implemented API security via a package or library.


Marjukka Niinioja posted one part Nordic APIs Platform Summit recap, one part guidance on API Documentation Developer Experience (DX). (Yours truly appears in a bit of captured Twitter swirl.) Marjukka argues that documentation should:

  • Go beyond the trivial; yes, a 'Search API' searches, but searches what? How often is that information updated? Are there limitations based on certain user roles?
  • Ensure sequence diagrams are from the callers perspective, not the internal development teams.
  • Describe more with less.


WRAPPING UP is a list of upcoming, in-person events held around the world. I've just updated with items through the month of November. One of the wonderful things about APIs is the vibrant and supportive community. If you haven't stopped by your local conference or meetup, give it a try. And if there's something missing from the list? Shooting me an email at and I'll work to get it added.
I'll end with a thank you for my Patreon sponsors. Together we ensure that I'm properly caffeinated when I tweet my outrage over bitcoin and GraphQL. Ah, good times, good times.

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.