API Contracts Defining the Next Phase of API Evangelist

Kin Lane
Written by

The next phase of API Evangelist will be defined by API contracts. The phrase API contracts has been thrown around loosely over the years to describe an OpenAPI definition, and used as part of a specific type of API testing where consumers are involved called API contract testing. I am co-opting and elevating the phrase API contracts as part of the next stage of evolution of API Evangelist, but also the API economy, using it as a vehicle to help govern the enterprise. Per my definition, an API contract represents a shared machine-readable understanding of the business and technical requirements established between the producer and consumers of programmatic interfaces used across desktop, web, mobile, device, and artificial intelligence applications. This is what I will be 100% focused on for the next couple of years when it comes to the governance of HTTP APIs and Webhooks across enterprises operating in any business sector.

I promised the wife I would keep this official open for business blog post shorter than my dramatic announcement that I was leaving Bloomberg. If you are interested in my thinking behind how I am using API contracts to deliver the next phase of API Evangelist, you can read through all of the bullet points from my previous announcement, but completely fluffed up beyond what anyone asked for as only the API Evangelist would do.

I had listed all of these elements out in my first post, but since then I have added a lot more color behind them. This list represents why I worked at Postman, why I worked at Bloomberg, and now why I am launching my API Evangelist services. I have a vision. I honed it working at Postman and Bloomberg, and now I am looking to take my vision to the next level across these three domains in a sustainable way.

  • API Evangelist - Stories, guidance, contracts, solutions, services, and conversations focused on the governance of enterprise HTTP APIs and Webhooks.
  • API Commons - APIs.json, common and community properties, vendor overlays, base APIs, blueprints, and rules for defining API contracts for anyone.
  • APIs.io - Profiling of public APIs across many business sectors using APIs.json, informing the API Commons, and API Evangelist services along the way.

APIs.io is a simple open-source API search engine, and API Commons are all the open-source building blocks I am cultivating through my work on APIs.io mapping the public API landscape. API Evangelist is where I tell stories, have conversations, and generate revenue through a handful of services to continue supporting my work for the next decade and beyond. My services are defined to support what I believe enterprises will need when it comes to API governance, while keeping me at a safe distance from the inner political workings of the enterprise (or startups), able to continue doing my research, having interesting conversations, and paying the bills.

Here is how it will all work. In order to access my services you will need to have an active API contract with me, either as an API producer or consumer. The price of an API contract will vary based upon the industry and the size of the entity I am working with, with the following support for any active API Evangelist Contract.

  • Source of Truth - Establishing a single GitHub, GitLab, or BitBucket repository to manage the contract, providing a single source of truth when it comes to the API contract, as well as all of its properties supporting the evolution of the API at the center.
  • Questions - Empowering teams to ask questions via issue or discussion via Git repository, or directly via email about the API lifecycle, governance, as well as the business or technical elements of producing an API for wider consumption.
  • Feedback - Providing feedback on the business and technical details of each API contract, helping facilitate feedback from consumers and other stakeholders, but also from the learnings across other private and public API contracts in use.
  • Guidance - Ensuring there is Just-in-Time API Guidance (TM) available throughout the life of an API contract, providing links to technological, business, and more policy focused guidance that helps teams producing API through their journey.
  • Provenance - Helping curate the provenance of each API contract as it evolves over time, documenting change, and cataloging the reviews, validation, certification, and conversation that occurs as each API moves forward and matures over time.

Initiating the management of an API contract with API Evangelist will get you access to those areas of support, but will also open you up to additional tactical services that I can help with as we work to manage your API contract together—-helping you achieve what you are looking for when it comes to API governance.

  • Mapping - Mapping the landscape of APIs, defining one or many contracts that already exist, helping to better understand the scope of existing API operations, and organize based upon the bounded context that matters most to leadership.
  • Creation - The creation of APIs.json business, OpenAPI technical, and other properties of a contract that are machine-readable, helping lay the groundwork for your API contracts, then helping guide you in refining and evolving them over time.
  • Review - Providing reviews of API contracts to identify existing patterns in use across API operations, then also providing feedback on anti-patterns, as well as additional patterns that could be applied to help improve API operations.
  • Certification - Certification of the properties of a contract, ensuring that they exist and are up to standards, and that individual API operations are accessible and are aligned with business use cases and are acceptable with contract schema.
  • Mediation - Provide mediation services when there are disagreements between owners and stakeholders producing APIs, as well as between producers and consumers over the business or technical details of an API, helping establish alignment.
  • Nudges - Weekly nudges on an agreed upon day regarding any questions, feedback, and changes being proposed by both API producer or consumer, helping keep the API lifecycle moving forward and maintain agreed upon levels of activity.

The pricing for each of these additional services will vary based upon the underlying contract, but also the number of API operations and stakeholders involved in the management of an API contract. Contract support, as well as additional service, are meant to get you plugged in with me at a tactical level when it comes to API governance, but I also offer a set of strategic services that will also help you get a handle on things across many APIs, and your entire organization.

  • Strategy - Helping define the overall API lifecycle and governance strategy, working with internal teams to evolve existing strategy, or help define a new strategy, bringing the experience you need to augment your existing resources.
  • Program - Laying the ground for your API governance program, providing the life cycle, policies, rules, schema, and contracts to kick-off your efforts, while laying the foundation for an API governance program that you can scale over time.
  • Platform - Defining the infrastructure beneath API operations, providing a common definition of the resources and capabilities needed across the API lifecycle, allowing for self-service and automation across the teams who are producing APIs.
  • Policies - Getting formal about the business of why you need API governance and properly wrapping your rules with the business rationale for why you do things like versioning, status codes, and other essentials to better align API operations.
  • Rules - Developing the machine-readable governance rules you need to validate and certify your API contracts in full, providing the rules, but also the automation needed to keep APIs moving forward in a consistent and repeatable way.
  • Schema - Defining the custom schema you need to round-off your API contracts with the business and technical details you need to produce APIs, ensuring the language you need for your API contracts properly defines what is happening.
  • Lifecycle - Get explicit about what each stage of the API producer and consumer lifecycle, as well as what actually occurs within each stage, organizing your governance rules by lifecycle stage to keep APIs moving forward across teams.
  • Guidance - Modular educational resources for APIs and API operations, providing markdown resources that provide an overview, but also insights into the business, technology, policies, and people side of API operations.
  • Evangelism - Helping enable you to evangelize your API lifecycle, policies, and guidance across your teams, and within your industry, helping build more awareness and gather feedback from stakeholders across your API operations.

I do not care how you approach the governance of your APIs. I don’t care if you start tactically, strategically, or a bit of both. I don’t care if you do bottom-up or top down, centralized or federated, or inside-out or outside-in. I don’t care if you are design-first or code-first. I don’t even care if you are api-first. I am just looking to manage your API contracts and govern your internal, 1st-party, and 3rd-party API relationships. I have a pretty opinionated view of API governance in 2024, something that has been building for a while, and it is something I am happy to share with you. You have two options, 1) Tune into my blog and participate in conversations, or 2) purchase one or more API contracts and engage with me directly regarding governing your enterprise APIs. I am just getting started, but I have a pretty solid contract-based approach to approach this, happy to have an introductory conversation to see how I might be able to help you better invest in your own API governance.

I have a year-long plan for rolling out API Evangelist services. It will take a lot of storytelling and conversations before people will understand what I am offering, and why they will need. Technologists beholden by investments trends will sit along sidelines and repeatedly point out there isn’t tooling adoption and scale for APIs.json contracts, without ever considering what an API contract actually does. This is fine. API contracts are for technologists, but they are primarily meant to be targeting business stakeholders, and begin shifting the conversations towards more alignment with business. Technological wizards of the API space are often unaware of how their perspective slows their own roll and regularly wet blankets the forward motion of APIs. I am keen on changing this and getting more business energy injected into the conversation. The tooling to support APIs.json contracts does not exist yet, and that is fine. I have a lot of work to understand what business stakeholders need to get more involved in the API lifecycle, and I think their tooling already exists, we just have to figure out how to seamless integrate into the API contract workflow via API, Git, and Webhooks.

My API governance services via API contracts aren’t designed for those in the know and already within the API echo chamber. My API governance services are meant to support business and engineering stakeholders within the enterprise who don’t already have the expertise, guidance, and leadership to move the API governance needle forward at scale across their businesses. I am looking to be the fractional API governance lead, confidant, advisor, and person helping do the mundane API policy, rules, reviews, and guidance alongside you. If you need help with getting started with API governance or helping shifting your API governance into a higher gear, feel free to initiate a contract to get going, or maybe just focus only on your top pain points as a contract starting point, or pick and choose tactical or strategy services that you think you will need. You are welcome to also just email me at [email protected] or find a 15 minute slot in my calendar to explore more around how I can help you. Don’t be shy. I am here to help, and if I can’t help, I’ll do my best to point you in the right direction.