The Ability to Link to API Service Provider Features in My Workshops and Storytelling

All of my API workshops are machine-readable, driven from a central YAML file that provides all the content and relevant links I need to deliver what I need during a single or multi-day API strategy workshop. One of the common elements of my workshops is links out to the relevant resource, providing access to services, tools, and other insight that supports whatever I’m covering in my workshop. There are two parts to this equation:

1. Me knowing to link to something

2. Being able to link to something that exists.

A number of API services and tooling I use don’t follow web practices and do not provide any easy way to link to a feature or other way of demonstrating the functionality that exists. The web is built on this concept, but along the way, within web and mobile applications, we have seemed to lose our understanding of this fundamental concept. There are endless situations where I’m using a service or tool and think that I should reference it in one of my workshops, but I can’t actually find any way to reference it as a simple URL. Value buried within a JavaScript nest, operating on the web, but not really behaving like you depend on the web.

Sometimes, I will take screenshots to illustrate the features of a tool or service I am using, but I’d rather have a clean URL and bookmark to a specific feature on a services page. I’d rather give my readers and workshop attendees the ability to do what I’m talking about, not just hear me talk about it. In a perfect world, every feature of a web application would have a single URL to locate said feature. Allowing me to more easily incorporate features into my storytelling and workshops, but alas, many UI/UX folks are purely thinking about usability and rarely thinking about instruct-ability, and being able to cite and reference a feature externally, using the fundamental building blocks of the web.

I understand that it isn’t easy for all application developers to think externally like this, but this is why I tell stories like this. To help folks think about the externalities of the value they are delivering. It is one of the fundamental features of doing business on the web — you can link to everything. However, I think we often forgot what makes the web so great, as we think about how to lock things down, erect walled gardens around our work, something that can quickly begin to work against us. This is why doing APIs is so important, as it can help us think outside of the walls of the gardens we are building and consider someone else’s view of the world. Something that can give us the edge when it comes to reaching a wider audience with whatever we are creating.