Everywhere I work I find myself reinventing the wheel when it comes to educational resources about APIs. There are many new topics to come along since I started in this game, but there are so many common building blocks you have to educate newcomers about-—we really should have a rich toolbox of content and other resources available for everyone to use at this point in the game. This is an area I dedicated API Evangelist to from 2010 through 2020, but I was just so busy trying to make a living I could never fully pulled off anything sustainable beyond the 4K blog posts here on the site. I can feel a resurgence of energy to produce these common building blocks here within my domain, but honestly it would make more sense as an official, community owned open source project.
One of my pet peeves is when API producers use up all of their words when describing their APIs explaining what REST, JSON, and HTTP is. These fundamental building blocks of API should get a single word mention with a link to a common definition via a community owned API resource center. We only need a single definition of REST, and everyone can link to it. Wikipedia can play a role in some of this, but then there are also a number of other API building blocks that need more context than Wikipedia can provide. There might as well be a single community-driven definition for REST, JSON, GraphQL, HTTP, WebSockets, as well as supporting elements like API keys, different types of API testing, and beyond. An open source set of educations resources covering modern APIs could provide links to external platforms like LinkedIn Learning, Youtube, GitHub, and wherever else API producers publish API knowledge, but it should really center around a common set of open source content and structured data focused exclusively on the modern application programming interface (API) (Been a while since I wrote that out).
Creating an API glossary, and authoritative guide to the API lifecycle is something I’ve seen waves of API service providers reinvent, only to disappear when they are acquired and then assimilated into the API Borg Collection (™). I’ve personally contributed to numerous of these API resource centers, only to see them wither on the vine and eventually go away like ProgrammableWeb did. It really bums me out that we have to perpetually reinvent the wheel on something that we all should see the collective value in coming together and building, instead we waste time and money in our walled gardens. For an industry focused on interoperability, reuse, and efficiency, we really suck at sharing resources and each focusing on what we are actually good at. At this point I have little faith that any single commercial entity, especially API service providers, possesses the attention span and goodwill to own the educational curriculum for the vast API realm.
I am going to invest some cycles in the info section of API Evangelist, pulling common building blocks from across my blog posts and organizing them in some (hopefully) coherent manner. However, I’d say I am just as an unreliable steward as the commercial interests, except I am just a moody and emotional writer who will burnout, hit reset, and take things in unsustainable directions. Oh well, I will keep working on cultivating the info section into a useful set of educational resources about APIs. Right now each page is just a paragraph or two, with links to any blog posts that share the set of tags assigned to the info module. Then I will think about what else I can publish. Maybe a video about each topic. Me just ranting for 2-3 minutes about JSON Schema or Headers. Wouldn’t that be fun? I am slowly working my way through all 4K+ blog posts here, cleaning out old useless posts, and mining the good ones for info nuggets about portals, docs, testing, governance, and all the other building blocks I used publish across many different subdomains, but only exist via my remaining storytelling in 2023.
OK, well, this is a project I don’t have the patience and time to lead, but really should exist. I wish someone would come along and manifest a truly well-managed, open source project providing an API glossary, curriculum, and other educational resources for API producers and consumers. We need a multi-protocol, programming language agnostic, and community-driven suite of educational resources for the beginner, intermediate, and advanced levels, spanning the entire world of modern API delivery. There is no escaping the involvement of commercial API service providers from this work, and we should welcome them in, but really it needs to be run like the AsyncAPI community, properly governing and building community around a set of modular, reusable, open source educational resources. I am happy to contribute to such a project, but my days of leading these efforts are over. I am just going to complain over here in my domain about what is needed, and throw my opinions around. All kidding aside, there needs to be new blood leading the next round of API investment-—I am going to stick with the world of API governance, regulation, and discovery, and leave the fundamentals and evangelism to the next generation.
