I have a new set of APIs and dashboard for editing APIs.json contracts, as well as individual APIs defined by OpenAPI. It will be a couple more months before it’s ready to share, but now that I can edit my APIs.json and OpenAPI through an API-driven user interface I am getting pretty excited about what is next—-overlaying my vision for what I call Just in Time API guidance. So far, the UI for my Just in Time API Guidance is a “sticky” sidebar that remains on the right-hand side when viewing the UI or YAML view of an APIs.json or OpeAPI artifacts, showing the results of real-time reviews of each artifact defined by Spectral rules. To help ground the next set of API and UI work I wanted to outline the capabilities of this new layer of my APIs.json contract management.
Rules Driven
My Just-in-Time API Guidance Kiosk is a listing of Spectral rules applied to an APIs.json and OpenAPI, but I will be elevating this listing of rules output beyond the linting approach taken by many other API service and tooling providers. I show negative as well as positive results for rules, but I will also round these rules off with other elements that help differentiate my approach to API governance from other providers. Rules are mapped to individual API.json or OpenAPI properties, but also provide a bridge to policies, guidance, and other defining elements of API contracts and the APIs they contain. A rule can be applied to each API contract and APIs, but the rule itself, and the conversation and iteration of these rules are accessible within the context of each individual review—-moving forward APIs, but also API governance in the same motion.
Access Filtered
Which rules that are run are first and foremost filtered by the access of each API. Meaning you get different rules if it is an internal, 1st-party, or 3rd-party API. Each of these APIs will have different needs based upon what access is available, and the number of rules being run against an internal API will be far fewer than it will be for a 3rd-party APIs. The Just-in-Time API guidance kiosks must be aware out of the gate regarding the access of each API—-this is critical for reducing information overload. The access defined by each APIs.json contract will set the stage for which ruleset gets run, something the user will be able to adjust for each of their contracts—-something that will set in motion a different API journey for each team that is producing APIs.
Policy Filtered
The rules that get run against APIs will be also potentially filtered by the policies which organize them. Anyone working with an API contract or individual API can choose to see the rules based upon each API policy. This means that users can choose to see the individual rules that apply to metadata, documentation, schema, and other key elements. Policies are still very technical, but they are more aligned with business goals and operational objectives driving API governance, and allow anyone to focus on specific groups of rules that satisfy different areas of concern. Policies are linked to each area of an API strategy which will drive reporting, the guidance that helps move teams forward, and connect API governance to different areas of experience outlined below.
Lifecycle Filtered
I’d also like to filter my kiosk based upon the API lifecycle. If an API contract has an API lifecycle applied to it I’d like to allow the filtering of rules in the kiosk based upon each stage of the life cycle. Allowing for the filtering of rules by each stage of the API lifecycle will help teams deliver on API standardization and governance in a deliberate order. This lifecycle approach to Just-in-Time API guidance will help teams focus on what is needed within each individual stage, and leave other rules to be done during future stages. I can envision teams also being able to explore what is needed for future stages early on (shift left), to help reduce the confusion that can exist from teams who do not have a lot of experience delivering APIs, and bring more visibility to API operations.
Experience Filtered
All API policies have experience tags applied to them, which also allows the rules supporting each policy to be grouped and filtered based upon how it impacts experience. This means things like design, documentation, mocking, SDKs, testing, security, and other common areas of developer experience can be used to filter the rules that are applied. This allows teams to focus on improving specific problem areas, investing in naming, summaries, and descriptions needed to enrich documentation, or the examples that are used in mocking and sandboxes. The experience filter for the Just-in-Time API Guidance kiosk allows teams to not be overwhelmed with everything needed across the API lifecycle and work on just what is needed to improve the experience in meaningful areas.
Next Three Steps
One thing I’ve learned over and over talking about APIs is how you can quickly overwhelm people with too much information. I want the Just-in-Time API Guidance kiosk to only show the next three or so steps that anyone can take. I want to find an elegant way to show just a couple things that need work, while also showcasing what has been done. API guidance should walk teams producing or consuming through what is needed next, without overwhelming with everything that is next, helping reduce the anxiety encountered working with APIs. It should be easy for users to navigate beyond the next three steps, but the kiosk interface should always emphasize keeping things simple and provide easy stepping stones for API producers and consumers to use throughout their journey.
Helpful Guidance
API rules are organized by API policies, which are linked to API guidance. Guidance is defined as one or two paragraphs of text providing an overview, with additional sections covering the business, technology, policies, and people details, a supporting video, and maybe some reference links. API guidance should focus on the APIs.json or OpenAPI property each individual rule is applied to, but should also be translated through the business reasons each individual area of API governance is needed, and provide the how and why of ensuring an API is compliant. Guidance should provide everything a team needs to overcome each API governance obstacle that emerges across the API lifecycle, allowing teams to read the documentation for exactly what they need, when they need it.
Sleeping on It
I want each rule to be something you can snooze. Allowing teams to sleep on items and work their way through each policy and rule in their own way. Rules will always show back up, but the kiosk should give teams some agency over how they ensure their APIs are compliant. The snooze button for API governance (guidance) is one way we can make sure governance isn’t a bottleneck and give teams a little more control in a seemingly endless list of API governance rules, reducing friction when possible, but still requiring teams to get the work done. I’d also like to work to better understand how teams navigate through rules and utilize a snooze button, keeping the history of how API governance rules are snoozed and in what order they are tackled to help refine how the kiosk works over time.
Scope Clarity
The Just-in-Time API Guidance kiosk will help reduce the API operational scope confusion I see regularly across the enterprise. There is a different set of guidance for OpenAPI than there is for APIs.json. There are many rules that are intertwined, but when working with an APIs.json contract for an API you are governing the operational scope of your API, and when working with an OpenAPI you are at the individual API scope level. Not having clarity regarding which scope we are talking about is a common point of friction for API operations and teams. I am looking to bring more clarity regarding scope into API conversations through separate API artifacts and API rule sets that are used to power an abstraction layer that reduce the complexity of how we produce and consume APIs.
Request Exceptions
In my opinion, you should be able to get around any rule with an exception. I will be linking up each rule to the underlying GitHub issues behind each API, allowing anyone to request an exception to a rule, and provide the reason why. Exceptions should be documented, and can be used to automate exceptions as part of API governance using the GitHub API and webhooks. Exceptions will remain on the permanent record of any team, and be recalled as part of each future version of developer for an API. Exceptions for API governance rules can be reported upon as part of wider API strategy reporting, but can also be used as a feedback loop for refining API policies and rules based upon exceptions from teams producing APIs, making the evolution of API governance self-service as part of API reviews.
API Platform Kiosk
My API Evangelist platform Just-in-Time API Guidance kiosk should guide people who are producing and consuming APIs. Right now I am focused on how this works for technical stakeholders, once I get this side of things up and running I will flip things over and deliver a separate kiosk for business stakeholders that is driven from the strategy side. Policies are also linked to areas of the API strategy, further reducing 75+ API policies into 25+ strategy areas, which I can also link to experience areas. This will allow me to build a kiosk for business stakeholders and leadership that will compliment the high level API reporting I am working on to show the progress of API governance across the enterprise, by domain, team, or other meaningful bounded context to business leadership.
I am hopeful that my Just-in-Time API Guidance kiosk will help address much of the information overload people are subjected to in the API space. It is lonely being at this level of API operations. There are only a handful of people in the space who can talk about things confidently at this level, and most everyone else just runs away. The big trick is going to be geo locating where someone exists within the matrix as they stand in front of my Just-in-Time API Guidance kiosk—-there is a lot of context needed before you can confidently and accurately guide someone forward in their API journey. I am getting better at identifying where people are on their own journey, but my kiosk should help me scale this understanding, while also becoming more effective over time regarding how I help folks know which subway train they should hop to to get where they want to be in any given moment.
