People don’t read documentation. People don’t have time to read books. But, I find people pretty receptive to absorbing API guidance in bite-size snackable chunks. My last book The API-First Transformation that I wrote while at Postman had the seeds of what I mean by guidance, but I define all my guidance as simple Jekyll powered YAML artifacts that help me modularize and reuse API guidance across my stories. The one thing that didn’t make it into the API-First Transformation book was the blueprints and links to complete guidance, which is something I am now finishing as part of my API Evangelist Guidance work to complement the API governance services I will be offering beginning this fall. I’ve been cultivating this guidance for the last fifteen years, I just now have the framework and suite of services for making them available in the moment across the API lifecycle to API producers and consumers.
When I conduct a review on an API contract I will link guidance with every piece of my feedback via the README, issues, and pull requests associated with the review of the APIs.jon, OpenAPI, and other artifacts included in the contract for APIs. Guidance is linked with contract feedback and reviews, providing API education in the. Moment, relevant to whatever policy and rules were encountered as part of ongoing API contract support via feedback and reviews. In my opinion API guidance should be available for search and browsing, but it should more importantly be right at your fingertips when you need it the most—translating every moment across the API lifecycle into a teachable moment. Just-in-Time API Guidance is designed to be available and consumed in the moment, but evolving over time with each engagement, helping improve API governance guidance based. Upon the realities on the ground.
Every piece of API Evangelist Guidance will have a public layer, providing an overview of each area of API governance, but it will also possess a business, technology, policies, and people portion which will only be available to my customers who have open API contracts with me. I’ve long given away API knowledge, which I will continue doing, but this round I am looking to also fund my work partially with my guidance. My guidance spans the entire API lifecycle and focuses on the common building blocks I’ve seen in action over the last fifteen years, capturing one or two paragraphs, supporting video, as well as other resources into a single module that can be linked up as part of emails, blog posts, but more importantly API contract reviews. People today rarely learn in any strategy or preemptive mode, but when down on the factory floor under pressure to deliver new products and features, I find they tend to be more open to being taught how to accomplish a specific task, why it matters to the overall business, as well as potentially how it fits in with other tasks they are having to tackle throughout the course of a day or week.
Just-in-Time API Guidance is a static YAML + Markdown + Links, but it is also ever-evolving based upon every engagement in a self-service or in-person review. Each piece of guidance is time stamped so that I will evolve and roll-over with time, but their usage is designed to gather feedback with each reference and usage to answer a question, shared as part of a blog post, or via a link in self-service or in-person guidance. The goal is to be able to identify aging guidance, but also evolve and mature guidance in the same way we do other artifacts involved in the API lifecycle. Business API contracts evolve and improve over time. Technical API contracts like OpenAPI evolve and improve over time. Governance artifacts like policies and rules evolve and improve over time. So should guidance. Just-in-Time API Guidance is designed to unlock forward momentum business and engineering stakeholders producing APIs, but they are also meant to accumulate knowledge that contributes to the overall forward momentum of the enterprise.
One additional footnote to my Just-in-Time API Guidance might not mean much for others, but it means everything to me. Each piece of guidance has a video that is recorded somewhere in New York City. I wander the city streets, buildings, and subways, and when I stop and find an interesting backdrop representing the system that is New York City, I talk through a single piece of guidance recording a 60 minute video. My mission is two-fold here, 1) get me away from the computer and walk around getting exercise, and 2) use the New York City system as a muse for unwinding the complexity of API systems. I find it peaceful to be tucked back in a corner of the vast subway system talking about the relevance of a 201 status code for POST API operations. I am unsure if people will notice or care, but the approach is helping me work my way through a huge amount of content, make sure each piece of guidance with 60 second videos, but also make sure I am healthier and happier, and getting away from my desk each day. Once again my work is guiding me, as well as guiding others, when it comes to making sense of the physical and digital world around us.
I have written and rewritten this API guidance multiple times over the years, as part of my API Journey work, or my API-First Transformation work, and now I will be offering it as part of my API Evangelist Just-in-Time Guidance that compliments my API Evangelist services. I was just going to write a book, but I am more convinced that it will reach a wider audience delivered as Just-in-Time Guidance as part of questions, stories, and reviews. Very few people have the interest, space, and mental bandwidth to read a book on API governance, but when someone gets stuck or finds themselves with negative or positive feedback during an API governance review, they are a little more motivated to learn about what is happening and why it matters in the big picture. I believe that API governance should be invisible and part of everything around us, and only becomes visible in the form of guard rails helping people make their way through the API world, and this is Just-in-Time API Guidance.
