Enterprise, Community, and Government API Commons

As I begin to work on renewing one of my existing API projects, I wanted to sit back for an afternoon and assess where things are. I see APIs everywhere. I see them on my work to work powering my city’s transit system all the way to the badge I swipe when I enter the building for work. I see APIs as I message with my wife, get my news, and make a reservation for dinner this evening. APIs are ubiquitous while also being incredibly invisible. APIs touch every part of our daily lives, but most people don’t see them, and those who do often take them for granted. I am mesmerized by the diff between how I see the sprawling digital world around me and how others, even those in tech see the digital landscape.

I’ve been studying web APIs since 2010. I’ve seen all the dimensions of APIs, originating with FTP, email, SOAP, and other incarnations–all the way to what we know and experience today. What caught my attention about web APIs was that this accidental experiment had jumped out of the enterprise IT laboratory earlier this century, becoming something we collectively call REST, Web, or simply HTTP APIs. We didn’t realize that we were all witnessing something very special back in 2000, something that is still growing and expanding today, except that now it is something we are seeing capitalism suck much of the nutrients which had given the last couple of decades its forward momentum. This is the intersection of technology, business, people, and policy that study, pay attention to, and hope to influence with my storytelling.

As usual, I find myself working to find my way through all the noise out there and stay true to what is important, but hopefully also what also matters to humans in a world that rarely pauses and cares for humans, and prefers to be moving at digital speeds. I am fortunate that I do not have to pander to the latest wave of the technology sector, and I get to spend this weekend thinking deeply about my API research over the last decade. I am coming up for air from work and the digital venture-backed tech hustle, to think deeply and guide my ongoing work with APIs.json, APIs, and API Commons, continuing to use my API Evangelist voice and lens. This is what APIs are all about for me, and I find renewed energy in resisting all the noise of each moment and do my best to connect the dots to produce a more meaningful picture of the landscape, and hopefully equip myself with some stories that will get me through the next couple of decades.

Before I get to work on version 2.0 of API Commons, I wanted to take a moment and think deeply about why APIs matter today, and how the API Commons could be used to codify what we just experienced in the last 25 years of this century, and help us take us into the future in a less exploitative and more balanced way. I’ve learned a lot by studying APIs over the last quarter century, and while I regularly am tempted to walk away from it all, I can’t help but muster the energy to share what I have seen, and use it to hopefully shape what is next. There is no escaping the Internet, or putting it back in the bottle. We have to wrestle with what we’ve created. I also acknowledge there is no utopian vision of either the digital or physical worlds, and humans are very messy, creative, emotional, and beautiful—-I have to take all of this into consideration as I share what my vision of the API Commons can be.

The Enterprise API Commons

This moment we are experiencing began picking up speed at the turn of the century as a new breed of startup business emerged and began using Internet technology in a much more transparent, collaborative, iterative, and digital manner. Salesforce, Amazon, and eBay were just a handful of the pioneers who began to think beyond any single application they controlled and began providing simple, but powerful web APIs for others to build applications and integrations with. These early startups saw beyond the potential of the web applications they could develop for themselves, and saw the opportunity in providing the raw digital resources they needed in their own applications, but also any other 3rd party application and integration in their ecosystem—-even potential competitors, or acquisitions.

The approach of these early pioneers fueled subsequent social, and emerging cloud waves of innovation, setting the stage for the mobile evolution of our personal and professional lives. Lightweight and scrappy web APIs were well suited to what was needed in delivering the applications and experiences we were beginning to deliver via our mobile devices. You can see essence of why API works in the now infamous Jeff Bezos mandate ordering everyone at Amazon to interact with each other using APIs, and you can see the blueprint alive an well via Stripe, Twilio, and many other tech industry commodities like payments, messages, images, and videos. This blueprint has been proven to work, and is still being applied across many public API platforms, but it is one that is besieged from both those who understand as well as those who do not understand what APIs are and why they work-—this narrative is looking to highlight, account for, and defend against this intentional and unintentional besiegement.

To help bring my vision of the API Commons up to an adequate state, I want to explore more of the technical, business, and political details of what the API Commons will serve. I am looking for the API Commons strategy and vision to capture everything that brought us here, but also address much of why we still can’t seem to ever find our full mojo and momentum due to the gravity and inevitability of capitalism, and how it will often do the “wrong” thing despite all the evidence on the table. Highly successful APIs begin out in the open via a common enterprise space that is available on the open web, something which seems counterintuitive to business leadership who’s job, as they see it, is to lock up any value generated, and establish command and control over the supply and demand of infinitely available digital resources.

The most significant signs of the health of any enterprise organization can be seen present in the availability, visibility, inclusiveness, and capability of these four publicly available doorways which look into the corporate digital soul at the center of the transformation EVERY enterprise is going through right now.

Developer Portal - A dedicated and vibrant public developer portal that isn’t just for technical developers, but anyone who is involved in the development of applications and integrations. Visit SalesForce, Amazon, eBay, Facebook, Google, Stripe, Twilio, and other leading API providers portals to understand what a healthy portal looks like. I will cover the essential building blocks of a developer portal, as well as the onboarding and other experiences that are needed for a successful API portal, but this bullet is just about opening up this story with the importance of a portal to the enterprise commons. Your portal experience cannot be just about developers or documentation, or just a section of your help and support, and it must speak to business as well as technical people and it MUST not be behind a paywall-—you can charge for APIs, but not the portal experience.
GitHub Organization - If you study the online presence of many successful API producers you will find that their GitHub Organization plays just as important of a role as their API portal does, with the portal oftentimes running as just one of many building blocks within the GitHub Organization. A public GitHub organization is much more than any code artifacts that may be stored within each repository. The enterprise GitHub organization can power the portal, documentation and other content needed as part of the enterprise common, but it also make your machine-readable API artifacts forkable and collaborative, reveal the open source your enterprise forks and puts to work, and many other rich signals business people will often take for granted when it comes to not just providing the nutrients your API ecosystem will need.
API Gateway - Your API gateway is a HUGE part of the enterprise common whether you want to see it or not. You might think your portal is the face of your enterprise API operations, but it is also your “gateway”-—it is just much less visible and tangible to normal people. The strength, security, agility, and velocity of your API gateway will set the tone of your API operations, ecosystem, and the applications and integrations they power. Whether or not your API gateway is well understood and accessible to IT leadership as well as developers on the ground floor will dictate the public face of your business across 1st party and 3rd party applications and integrations for decades–“Seeing” your API gateways as visible as your developer portal is an essential aspect of your digital transformation.
Integrated Development Environment (IDE) - The IDE is central to the developer experience, no matter what API you are using or what programming language you use. The accessibility of your API program as well as individual APIs within VSCode and other popular APIs will shape the future of your business. While many investors believe all roads in software and IT should lead to the cloud, and it often does for many business and technical services, you are actually hurting your public image by not having a presence via IDE as plugins, artifacts, SDKs, tests, and other common tools in the modern developer toolbox. In the modern API landscape, you want to be the Makita, DeWalt, and Craftsmen of the developer toolbox, with your brand littered throughout their IDE experience in useful and meaningful ways. If you make their life easy there, you are much more likely to get them to step into your cloud platform on a regular basis.

From a behavioral perspective (which is really all you got), these are the areas you size up the health, confidence, and viability of any enterprise in the digital era. I can rank any business on the first three elements (portal + org + gateway), with the fourth one being a pretty advanced concept that is still playing out. As you will see, it isn’t just the availability, access, and activity of these aspects of enterprise operations, it is how you wield them, which goes well beyond just publishing an API and documentation publicly. Anytime someone tells me you are giving something away by having these areas of your operations publicly available, I immediately know where they exist on the API journey. To understand the scope in which these areas play across the technology landscape, just take a moment to assess where Microsoft has been investing–they are rocking the investment in GitHub, Gateway, and IDE, but alas they kind of suck at the portal game–3 out of 4.

Common API Building Blocks

I have looked at all the public API portals. I have. Sure there are always new ones I haven’t seen, but I’ve looked at so many over the years, and studied how they work or don’t work for so long now, I can iterate what the common building blocks are from heart, and point you to the good and bad ones. However, there are always new ones emerging through innovation that are occurring—-I saw a “Quantum Computing” option in an API portal just last night—-but the most common aspects of portals are a proven thing. To understand how these building blocks work in concert, it helps to organize them into logical groupings that help better demonstrate the often invisible business value they bring. This is something is often taken for granted by developers and overlooked by business leadership-—it is a small handful of folks who understand how to use them in concert at scale to shape an API ecosystem.

API Discovery

Can people find your API? Can your employees, consumers, and yes, your competitors find your APIs? It is a scary thought, but the reasons your APIs are hard to find within the enterprise are the same reasons why your APIs are hard to find on the open web. Discovering APIs, no matter whether you are technical or not, is one of the most telling aspects of why the API Commons matters, and API discovery building blocks are so essential.

APIs.json - Having a machine-readable, or network of machine-readable APIs.json artifacts describing all of the building blocks of your API operations is essential to shifting all of this into the next gear to power AI, and whatever else is needed in the future.
Metadata - Your API operations, your APIs, teams, tools, and other building blocks must have the metadata they need to be searched, browsed, and discovered, ensuring that all APIs have accurate and rich information about what they do for consumers.
Filters - There has to be ratings, semantics, tags, and other filters in place that help find the signal within the noise with API discovery-—it is noisy down here where the APIs are powering all of our applications and you have to be able to filter it out.

The lack of discovery is the biggest problem ailing not just the world of APIs, but the wider technology landscape they power. The lack of API discovery is just a symptom of a larger illness that you can see present in the lack of a public API portal, or one that is locked down or inactive. A public API portal and catalog is a mirror of what you find within an enterprise, and if API discovery is a problem, I recommend looking for solutions from the outside-in-—sunlight can work wonders.

Frictionless Onboarding

Once you find an API, the next logical step is to onboard with it. After discovery, this is the number one place you will find friction for producers who are early on in their journey, and you will find flexibility and control for producers who are further along in their journey. These are the building blocks business leadership is looking for over their digital resources and capabilities, but are often unaware that they exist because they are hidden away in IT led initiatives.

Documentation - In an API-first world everything is documented using simple plain language, describing the entire surface area of each individual API, but organized in a way that makes sense to consumers and what they want to be doing with an API.
Getting Started - Having each of the steps that API consumers will need to get started with an API is a great way for producers to pause and put on their consumers hat to think through what it will take for consumers to onboard, and how easy or hard it is.
Authentication - Providing a secure and standardized way for API consumers to properly authenticate with an API and identify who they are and associate it with a known account that is adequately associated with an individual or business profile.
Authorization - Getting into the details of what each authenticated API consumer does with digital resources, providing fine-grained access controls over any content, data, or other digital resource being made available to an application by valid consumers.
Applications - Establishing a single definition of each API consumer that defines how digital resources being made available via APIs will be applied, representing the Venn diagram of authentication, authorization, but also plans and limits being applied.
Plans - Outlining what the pricing and access levels for API consumers are, providing clear plan tiers that represent what both API producer and consumer are needing, establishing the right amount of plans to support new and existing API consumers.
Rate Limits - Establish clear rate limits across all APIs, associated with specific plan tiers, and attached to each individual application, ensuring that nobody is abusing API resources, backend systems, and all API consumers can still get what they need.
SDKs - Providing high quality SDKs in a variety of programming languages, which are often generated using machine-readable artifacts, to provide consistent software development kits that abstract away the most common aspects of integration for developers.

These building blocks are organized under the onboarding category because I am wearing my API consumer hat, but as an API producer this is where you understand the level of control your APIs offer, reducing any concerns around the public nature of your portal to something that just doesn’t matter anymore. Modern API management, combined with a portal and common API onboarding building blocks give you what you need to properly protect your business interests–if you can’t see this, you aren’t experienced, and your customers and competition know this.

Machine-Readable Artifacts

APIs are about making the technical details of our API operations more visible to both producers and consumers, and there are a handful of machine-readable artifacts that are increasingly being demanded by consumers, and producers are also using to ensure everyone is on the same page.

AsyncAPI - Providing an artifact to describe our event-driven API infrastructure.
RSS / Atom Feed - A good ol Atom or RSS feed for our blog or other property.
GraphQL Schema - A GraphQL schema describing the graph APIs we make available.
JSON Schema - Allowing us to define and validate the objects we pass back and forth.
Brown M&Ms - This is real, just here to make sure you are reading the contract through.
OpenAPI - Providing an artifact to describe our request and response API infrastructure.
Postman Collection - Publishing collections that can be used in the Postman API client.

These artifacts are used to integrate and automate API operations, and help make integrations more self-service. However, they are also used to align both producer and consumer throughout the life of an API, and are used to generate documentation, SDKs, and help standardize APIs at scale.

Covering the Legal

The legal side of operating your business is an unavoidable part of doing APIs, and it is in your best interest to publish the common set of legal building blocks you will find present across any of the successful API producers, making sure your interests are protected, while also protecting those of your consumers, and end-users.

Terms of Service - Providing common sense and legally binding terms of service that apply to your APIs.
Privacy Policy - Making sure that the privacy of all stakeholders is properly addressed and published for all.
Licensing - Establish the license of your backend, interface, as well as the artifacts and code you make available.

The legal building blocks of API provides you with another dimension of control over your API operations, ensuring that you have properly addressed legal, regulatory, and privacy concerns that will always be a very real aspect of doing business on the web, even if it is less visible due to APIs.

Demonstrated Quality

The quality of your API operations will speak for itself, but you know that API producers who are confident and proud of their services will be much more likely to share their process, as well as the results of what goes into the quality of the products they offer—with the following building blocks front and center for leading APIs.

Testing - Validation, contract, and other types of API testing accessible and available for both producer and consumer.
Performance - Full transparency regarding the performance of API products across all relevant regions where available.
Security - Showcasing the security practices in place and the testing as well as results that have gone into API security.

I am fully aware of what a sensitive subject this is for enterprise organizations, but everyone involved knows that this is what will ultimately matter most for consumers when it comes to putting API products to work in their own applications, and integrations, so it makes sense to bake in across the board as part of API operations whenever you can.

Observable by Default

We addressed part of observable and the challenge with seeing APIs above with discovery, documentation, and other building blocks, but ensuring that every aspect of API operations observable has proven to be a challenging yet critical aspect of being able to operate and scale and find the right balance for any API powered business operations.

Status - Making it very clear whether a service is up or down, while providing history to understand overall reliability.
Dashboards - Ensuring there are dashboards for every aspect of observability available to both API producers and consumers.
Reports - Producing, fine-tuning, and perpetually optimizing the reporting that occurs across all levels of API operations.

Do not limit your API observability to the APIs themselves, and bake observability into operations, so that you can see where APIs are in their lifecycle. While there will undoubtedly be aspects of observability you won’t make available to consumers, making these building blocks accessible to consumers should be the default.

Consumer Engagement

Once an API consumer has integrated with an API, deeper engagement is required to keep them putting digital resources to use, expanding to new resources, and increasing API consumption over time. There are a handful of building blocks that are proven aspects of API management that keep consumers engaged, making the business of your APIs stickier.

Sign Up - Making it easy to sign up for a new account and begin putting APIs to work with as little friction as possible.
Log In - Don’t make consumers work when it comes to visiting your platform and logging in to engage—ensure that it is easy.
Accounts - Provide all of the account capabilities available via other platforms, and even allow for account interoperability.
Usage - Always help API consumers understand what their usage of each API is and where it fits in with their overall plan.
Billing - Provide billing for API consumption that is a transparent breakdown of plans, applications, rate limits, and usage.

This is where you keep API consumers coming back. This is where you engage with consumers and get to know your developers (KYD), making it easy for them to engage with your platform, and develop new and compelling ways to keep them coming back, being engaged, and discovering new resources, capabilities, and experiences–building trust over time.

Managing Change

Change is a constant in the world of technology, and there are proven building blocks that help API producers manage and communicate change—-keeping API consumers aware of what has changed, what will change, and making sure that there is always the proper rate of velocity involved with evolving the digital resources, capabilities, and experiences a platform provides.

Road Map - The details of what is being planned for the future of an API.
Change Log - The details of what has changed for each version of an API over time.
Deprecation - Properly communicating what will be going away and when.

API change management is all about being able to confidently and consistently being able to identify and communicate change, establishing the right amount of velocity between API producer and consumers—with overall velocity varying from industry to industry, and API to API—this is where you pull ahead of your competition, or you lag behind.

Product Feedback Loop

Your public API portal is an essential lifeline to feedback from your consumers, providing a rich two-way street for learning about your industry, or across industries, while also keeping your consumers up to speed with what is happening across the enterprise. There are a handful of common building blocks you will come across when browsing the portals of the API pioneers and leaders driving the feedback loop internally and externally.

Contact - Do not be afraid of having an email address published to engage with consumers of your API.
Support - Offer the expected free, but also paid support services to ensure consumers have what they need.
Blog - An active blog is one of the most important signals your API can put out, ensuring your story is told.
Forums - Operating your own, or participating in existing forums is a great way to understand your consumers.
Videos - Publishing videos, webinars, podcasts, and other media help open up your operations to your consumers.
Newsletter - Offering a recurring newsletter that shares what has been happening in a single digest is helpful.

Depending on the velocity and breadth of your APIs, and the trust you possess or do not possess with your consumers, these feedback loops will be essential to the velocity of your business, the product you produce, and how aligned they are with what your consumer need. This is where you find your new product ideas. This is where you validate new capabilities. This is where you acquire the talent you will need to grow your business. Without this feedback loop you will always be behind.

Enterprise API Orchestration

There are numerous other building blocks I could highlight such as sandboxes, integrations, and tutorials, but these are the most common building blocks of public API platforms. This is what I am looking to ensure the API Commons is in service of. These are all of the areas that matter when having conversations with enterprise business and technical leadership about why having a public API presence is so critical. This isn’t about whether you are giving away information to your competitors, and which APIs or applications consuming them should or should not access your digital resources, capabilities, and experiences. Those conversations happen down on the factory floor, supply chain, and wholesale and retail experience that occurs (or doesn’t) via your own enterprise commons. I am aware that all those bullets above might just look like words, but each of those words provides a knob or dial you can turn to optimize your business at scale, and these knobs and dials do not exist if you aren’t actively playing the API game.

The majority of these building blocks existed a decade ago. I was writing about them here on the blog in 2012. You can see evidence of how this blueprint works with Stripe, Twilio, Amazon, and many other small, medium, and large enterprise API platforms. However, even if you do all of this, you are not guaranteed success. There are many other factors that can come into play when it comes to enterprise leadership, industry forces, but also through the lack of imagination and greed that is ubiquitous across technology today. Open does not equal good. Open also does not mean a loss of control. Open will take more accountability, responsibility, and transparency. I have heard from day one of API Evangelist why enterprises can’t do public APIs or provide a public developer portal, while simultaneously hearing deep concerns regarding quality, velocity, and technical debt—-with almost no reflection of how the two are related. Take a moment to reflect on what it means when a developer says “this is just an internal API” — they are saying the bar is lower inside of a company. They are insulated.

I can’t talk every enterprise into having a publicly available developer portal, and fully understand how APIs can help them navigate their digital transformation. However, I can continue to tell stories here on API Evangelist that might change their mind, but I can also take what I know and produce more guidance, policies, and artifacts that enterprises can use to deliver on some of what I highlight above as part of the enterprise API commons. This is what I want API Commons to become. I want API Commons to become where you go to find tangible, applicable policies and artifacts that help you better deliver everything I just talked about with the humans involved with producing and consuming your APIs. I want to show you what I mean—-not just tell you. I want the API Commons where you come to learn and shop for what you need for the enterprise API Commons. I got my “API PHD” studying the portals, operations, APIs, and ecosystems of enterprise and startup API pioneers and innovators—-I am searching for the most meaningful way I can apply what I have learned at scale.

The Community API Commons

The API Commons began as a response to the Oracle vs. Google API copyright case back in 2013, and we are now rebooting using this vision as fuel. I was able to convince Steve of this latest vision when he recently came to NYC to stay with me, but now I want to set things in motion. API Commons was originally just a single machine-readable piece of this larger vision, and I think the name API Commons can carry forward much more than just a single API interface license. Honestly, after a decade of learning from the ongoing Oracle vs. Google copyright case I am acutely aware that there is much, much, much, much more that ails us than concerns around API copyright and patents. The rot goes much deeper, and the lack of imagination is greater than just the naming and ordering of our interfaces, yet the API copyright battle still is a critical part of the core of what API Commons is and needs to be.

The API Commons reflects everything I have learned at the intersection of the technology, business, and politics of APIs since 2010, and the learnings I am applying to my shift to focus on the technology, business, people, and policies of APIs going forward. I have one, maybe two more API cycles left in me, and while I may (or may not) have the energy for one more startup in my future, I am more concerned with properly laying the foundation we will need to tame this Wild West Technology Shitshow ™ in the coming years. I’ve seen how venture capital can suffocate API innovation by extracting more nutrients than it puts back. I’ve seen how big companies excel at weakening the role the government plays in the API game across the industries that matter. I want API Commons to be something that will survive and thrive in the inevitably toxic environment that is the tech sector. API does not equal good. There is no right way to do APIs, and there are plenty of proven wrong ways to do APIs. APIs are just as good at extracting value than they are at generating value. I want API Commons to be built with all of this in mind.

I set out to write this vision without fleshing out my vision of the enterprise API Commons, but found that I would need that narrative to set the table with the realities of operating an enterprise API platform, or more specifically a public enterprise API platform. But, I’ll let you in on a little secret—there is no difference between public and private. It is all in your head. All of our lives are on the Internet now, whether we like it or not. It just comes down to how high you want the bar to be for your business, and how in tune you are with where you are in your digital transformation, how far along the journey you are, as well as how far into the future you are able to see. I’ve been studying the electricity, telephone, radio, railroad, and television industries over the last couple of years, and thinking deeply about what went into helping standardize, regulate, and expand these industries safely. I want to add these learnings into my vision of what API Commons needs to be, but the API Commons vision begins with its most critical schema and building block—-APIs.json.

APIs.json

APIs.json is a machine-readable index for your API operations. It allows you to describe all of the API building blocks outlined above and drop it into the root of your developer portal. It is also the heart of the APIs.io search engine we are building to help us seed the services and tooling to support this open source API discovery format. APIs.json often gets confused with OpenAPI, which describes the surface area of your REST or HTTP APIs. But APIs.json is meant to describe the surface area of your API operations or a particular slice of your API operations, and you can index OpenAPI using your APIs.json, but you can also index much more using the key elements of an APIs.json index.

APIs - You can describe the name, description, tags, baseURL, and other metadata for each API being indexed using APIs.json.
Properties - All of the properties outlined above as part of the Enterprise API Commons can be indexed as an APIs.json property.
Includes - The include property allows you to group your API operations into different domains, lines of business, or tribal factions.
Networks - Allowing for networks of APIs.json to be linked together as groups of nodes that can be indexed and searched.
Overlays - The ability to overlay multiple APIs.json over each other to aggregate a specific set of API values into a single index.

APIs.json has always been a standalone specification, but moving forward will become the centerpiece of the API Commons, with licensing and all the other properties of an APIs.json index as common machine-readable schema. You see, APIs.json properties were always meant to index the human readable properties of API operations, but also the machine-readable properties, with the intent of translating all of them into machine-readable properties. The new API Commons will just shift this process into second gear. We saw what OpenAPI and AsyncAPI were doing to the API landscape, and we want the same for the rest of our API operations.

Community Schema

There are a range of existing artifacts in use across API operations to describe the surface areas of HTTP, TCP, and other APIs, which can also be published as APIs.json properties. These machine-readable artifacts are providing the technical details of what each API can do, and are increasingly being used to power documentation, but also being shared by providers via GItHub and other channels.

AsyncAPI - Providing an artifact to describe our event-driven API infrastructure.
RSS / Atom Feed - A good ol Atom or RSS feed for our blog or other property.
GraphQL Schema - A GraphQL schema describing the graph APIs we make available.
JSON Schema - Allowing us to define and validate the objects we pass back and forth.
Brown M&Ms - This isn’t real, it is just to make sure you read the contract all the way through.
OpenAPI - Providing an artifact to describe our request and response API infrastructure.
Postman Collection - Publishing collections that can be used in the Postman API client.

One thing that all of these schemas have in common is that they describe the technical bits of our APIs. The API Commons wants to leave this work to the existing players. The API Commons wants to translate the benefits these specifications have brought to APIs, but more evenly spread it across API operations, benefiting API discovery as well as across the entire API lifecycle. It is my opinion that there is no one spec to do it all, and there should be plenty of complementary and competing API specs.

Operational Schema

After showcasing existing schema, the purpose of the API Commons is to identify the most common building blocks used as APIs.json properties and ensure they are available in not just human-readable formats, but also machine-readable ones that can be used to automate onboarding and integration with APIs by any application, system, or agent. These are the building blocks we will need to automate the next generation of AI and applications, so let’s get busy making sure they are machine-readable and exist in the commons.

Getting Started - The distilled down steps you need to onboard with an API.
Authentication - How you obtain your application and keys used for authentication.
Plans - The business details of what it will cost you to actually put the API to use.
SDKs - Sharing what code is available to use when it comes to integrating with an API.
Licenses - The legal side of integrating an API into your applications.
Road Map - The details of what is being planned for the future of an API.
Change Log - the details of what has changed for each version of an API over time.

I already have a schema for all of these. They aren’t complicated. I just need to get them standardized and presented as part of the API Common GitHub organization and published to a new version of the website. I am not worried about them not being perfect—I am just looking to get the conversation started around what is actually needed. These aren’t new conversations for me, but ones that I am looking to amplify using this API Commons reboot.

Vendor Overlays

Overlapping with the properties in which common and community schema deliver value, I’d like to find a way to shine a light on the potential of APIs.json overlays when it comes to the enrichment of API operations. I have fleshed out the APIs.json overlay property using APIs.io Search, as well as API Evangelist Ratings, but I’d like to quickly evolve to address all of these essential areas:

Search - Fine tuning the names, summaries, descriptions, and tags to improve discovery.
Ratings - Applying a variety of Spectral-driven rules which each carry different points.
SDKs - Defining what software development kits are available for integrating with APIs.
Security - Looking at the security of APIs, and providing a summary of what is found.
Testing - Executing contracts and other types of tests and overlaying the results.
Monitoring - Keeping an eye on the uptime and performance of APIs being indexed.
Localization - Providing translation of names, summaries, descriptions, and tags for APIs.

These are just a handful of the introductory areas we’d like to see vendor overlays being invested in as part of the commons. We are confident that an open source set of schema defining these areas of our API operations combined with the commercial services brought to the table by vendors can coexist and be used to power API operations.

Resources and Capabilities

The schema I’ve covered so far is about standardizing the surface area of our API operations and APIs. I don’t want to stop there. I want to do it for the most common APIs out there. I am sorry, but we shouldn’t have to launch custom APIs for all of the most common digital resources we depend on to operate our businesses. There is no reason that the common digital resources and capabilities we depend on across API platforms should all be different.

Accounts - Why should all of my accounts use different APIs.
Contacts - There are existing contact standards, let’s build on these.
Events - One of the most competitive areas I know lacking interoperability.
Images - There is no reason to have to design an image API from scratch.
Messages - Ensure the entire message stack is represented as APIs.
Payments - There are existing API standards in play in the US and EU.
Videos - Like images, I should not have to create a video API ever.

These are just the top seven digital resources that we should have standardized, but let’s not stop there. Picture Schema.org, but for APIs. I am just talking about a ready to go OpenAPI or AsyncAPI and supporting JSON Schema for each of these resources. Why on earth should any developer anywhere craft their own OpenAPI for any of the most used digital resources and capabilities. I’ll make the seeding of resources and capabilities standard practice as I profile APIs for APIs.io, squinting, aggregating, and distilling the OpenAPIs I find down into reusable digital resources and capabilities anyone can use — hopefully others will do the same as well.

Community API Collaboration

I am using API Commons to translate all of the work I have been doing for over a decade on API Evangelist into actionable policies for the world of APIs. Most of what I am building already exists as part of my API research and storytelling. I am just looking to get more disciplined about not just publishing stories, but publishing actual usable machine-readable artifacts that can be applied as a single policy to guide public API operations. While there will undoubtedly be links to services and tooling where you can apply all of the schema the API Commons showcases and produces, I don’t envision the API Commons investing much in tooling anytime soon—-that doesn’t mean it won’t, it just isn’t the priority part of the vision for this reboot.

The API Commons began as licensing for your interfaces, but is now about providing the openly licensed interfaces you need for your APIs and your API operations. After watching the Oracle vs. Google copyright case reach the Supreme Court I realized that API providers and consumers care very little about copyright. It isn’t that it doesn’t matter, they just don’t see it or understand how it gums up the works until we see resulting litigation or regulation focused at the API intersection. So, I better get to work just producing the schema we will need to discover, but also automate, regulate, and govern API operations, rather than just tell stories about why it matters. I am a believer in enabling people to do the right thing over just trying to convince them they need to do the right thing.

I am exhausted from saying the same things over and over as the API Evangelist. I am exhausted from the willingness to reinvent the wheel in the API space due to lack of imagination, delusions of proprietary value, and just greedy short sightedness. API management was commoditized in 2015. You aren’t witnessing an unbundling of anything today. It is just the reality that we shouldn’t be competing on the essential building blocks of API operations, API requests, responses, and events of our proven digital infrastructure. We don’t need special snowflake payment, images, videos, messaging, and other proven digital resources and capabilities. We should only be competing on experiences, and the next generation of digital resources and capabilities. However, to get there we are not just going to need the standardization of the enterprise and community commons, there is one more critical dimension to all of this—government.

The Government API Commons

This is the side of my API Commons vision I have explored the least. This doesn’t mean I haven’t thought about the role of city, state, and federal governments-—I have a lot. I just haven’t explored the role of an API Commons that is focused on enabling governments to have a more meaningful impact on their constituents using APIs. Like other areas of the API reality like startups, the enterprise, investment, and the diverse industries I’ve worked in with APIs, I have a lot of thoughts on what the government should and shouldn’t be doing with APIs. Much of what I covered with the Enterprise API Commons above applies to the Government API Commons, but because of its role, there are some areas that need more attention.

Government APIs aren’t just about the government regulating APIs, it is about the government leading the API conversation. It will be acknowledging the role that both the public and private sector has on business and individual’s lives. This will be the first of many posts I write to try and flesh out the role that the government will play in the API Commons, and how this will be needed to stabilize and power both the Community and Enterprise API Commons. The future of APIs, and technology regulation depends on this intersection, and shifting from a focus on politics of APIs to more about API policy, while also still being honest about the business and technology of APIs is important.

Assume Your Role

The most important thing that the government can do when it comes to the API Commons is to actively be doing APIs. They already do. I’ve showcased many API efforts over the years, and will be something I continue doing in the future. We need more APIs from the government, but we also need them to assume their role as both API producer and consumer, as they also take the lead on regulating technology at the API layer—-which is really how you are going to be able to enable and influence things at scale.

API Producer - Government needs to stop treating producing APIs as an IT initiative and follow the lead of enterprise and begin to treat them as products — clearly different than a commercial product, but with many of the same forces in action.
API Consumer - We need to make it easier for government agencies to consume the APIs of the software and infrastructure they already use, but also make it easier for vendors to reach government agencies with digital resources and capabilities.
API Regulator - Being a regulator of APIs is already occurring in finance and healthcare, and something that will continue to pick up speed across other industries regulated by the government, and this area is ripe for interoperability and reuse.

I’d like to make the same argument as I did with the enterprise API Commons, in that the government API Commons needs to be public. Sunlight is a great disinfectant. We need to raise the bar when it comes to government interoperability, as well as the delivery of 1st and 3rd party applications and integrations that serve consistent interests. Look at what the Department of Veterans Affairs has done with their developer portal, or CMS has done with Blue Button. This isn’t rookie level stuff, and it is properly serving constituents, and demonstrating how the government can lead the API conversation, setting the right tone across other government agencies.

Standards

Producing and consuming APIs is the most important thing that the government can do, but when it comes to specifically standardizing, regulating, and governing APIs, there are a handful of dimensions to consider. These are the most important dimensions we can consider when it comes to the Government API Commons, and something I will do more writing about to flesh out in the near future—once I stand up the next iteration of the API Commons.

Security - Continuing building on NIST and other efforts, but focus on OAuth to help deliver 3.0 of API authentication and authorization.
Privacy - Continuing building on GDPR and CCPA, but quickly consider how you will defend it from dilution and friction that renders it useless.
Industry - Invest in the delivery of standardized APIs like you already do for healthcare using FHIR, but do this for all of the important industries.
Portals - Require enterprise to have a publicly available API portal as outlined above, opening the door to future regulation or consumption of APIs.
Properties - Invest in regulating the properties that matter most to industry regulation, beyond just the surface area of the APIs in question.
APIs - Make sure that all government agencies are reusing the same APIs, reducing SDK and integration costs, and driving interoperability.

I have many agency APIs defined as APIs.json and OpenAPI, so it will be easy for me to seed some schema in the API Commons—-encouraging other agencies to adopt and reuse the patterns. I also need to catch up again on all the security and privacy efforts already in motion at NIST and other agencies—-adding them to the existing stack of schema to adopt. I think I produced a common set of schema from across city, county, state, and federal agencies a while back. I just have to find my blog post on it.

I will go back through all of my government API work and use this work to plant seeds for the Governance API Commons—-not much has changed. There is a lot of low hanging fruit when it comes to aggregating existing schemas and putting them forward as OpenAPI. I just need to do the work. I’ve done much of the work to spider government agencies looking for API patterns, I just need to organize them as APIs.json and OpenAPI as part of my APIs.io profiling, producing some government search nodes. This part of my narrative is the least fleshed out, but I am confident I have plenty of material to get it up to the same levels as the enterprise and community portions API Commons vision.

API Commons Network

We recently added a proposal to add the network property to APIs.json, which is being used to organize the many individual search nodes like cloud, payments, and messaging. Before that we added the overlay property to help incentivize vendors to add value to not just APIs.io search index using APIs.json overlays, but also anywhere you find APIs.json. Our goal is to offer up different ways of rolling out networks of APIs, but also networks of API services and tooling over the top of them.

To help drive work on schema in the API Commons I am envisioning three individual dimensions initially to approach the development of new schema by a mix of public and private sector interests:

Projects - I propose breaking work down into individual micro projects around each individual schema—keeping things small, meaningful, and modular.
Partners - Bring in public or private sector, as well as other open source contributors to help power an advertising network that is in service of the commons.
Grants - I have begun a YAML inventory of grant opportunities from foundations, government agencies, and other sources to potentially match with projects.

I’d like to figure out a contribution-based framework for the advertising and other featured aspects of operating an API search engine, or a network of API search engines. Meaning, if you help build and refine the index, you can get preferential treatment when it comes to network perks, advertising, and such. This is one reason I am running everything on GitHub, is that the opportunity to manage projects as individual repositories with their own issues, permissions, data, and content-—keeping things open and transparent, while still leveraging the network effect GitHub provides.

APIs.io Search Engine

I didn’t want to tell the stories of API Commons without including an acknowledgement of the role that commercial private sector services and tooling will play. While APIs.io is an open source API search engine, there are parts of the API search engine Steve and I intend to eventually use to generate revenue. We don’t know what these parts are yet, and we are still just exploring what is possible, but we both consider APIs.io to be a commercial partnership—-contrasted with APIs.json and the API Commons, which are our open source work we feel are essential to power the API economy.

I am not sure where APIs.io will go, all I can tell you about is what it currently is, and where we hope to take it. Right now I have a couple hundred API providers with a couple thousand APIs available across them defined as APIs.json. I’ve published version 1.0 of the search engine, and getting closer to a usable version 2.0 of the search engine. These are the core dimensions of the API search engine as it stands today with the version I’d like to release next.

API Search - There is a search bar that returns APIs that are indexed as part of the search engine.
API Network - Breaking APIs down into networks to make them easier to manage, search, and browse.
API Browsing - You can browse the API providers and their APIs using each of the network nodes.
API Properties - You can browse APIs based upon the properties they have indexed using APIs.json.
API Tags - Make APIs browse-able based upon the tags that are applied to APIs and their OpenAPIs.
API Rules - Organizing APIs by each of the rules used to rate the API operations and each API.

That is all we have planned for now. We will be evolving the layout of the site now that we’ve moved to use Bootstrap, making it look more polished and visual. Right now we are focused on indexing high quality APIs and refining the process for how we discover, profile, and organize into separate networks. API discovery is essential to this entire API Commons vision, and tooling in support of APIs.json is critical to the success and adoption of schema in the API Commons.

We have built APIs.io using GitHub Pages, using Jekyll and Bootstrap for the user interface layer, and YAML for the underlying data layer. This will make each APIs.io search node forkable and something that can be run via any GItHub organization or on-premise—this reality has pushed us to split up the search for it into two flavors:

Local Search - The simple client-side JavaScript search that uses the localized APIs.json in each GitHub node as the search index, crawling and returning results.
Cloud Search - This is where we will begin to offer a more powerful, fast, and richer search experience across all of the APIs being indexed as part of the search engine.

While cloud search isn’t something we are charging for now, it is something we’d likely offer a premium or on-premise search experience at some point in the future. We don’t have any plans to monetize APIs.io in the near future. It is just an open-source side hustle at this point, but who knows what the future will hold if we can keep growing the index and the value of the content. APis.io is meant to be a search engine, but think of it also as a crawler that is mapping out the API landscape, producing the properties and schema we need to power the API Commons.

API Evangelist

Last but not least, there is the role that API Evangelist plays in all of this. Nothing much changes here. I’ll keep it as my soap box, and part of my personal domain. I am working to clean up some of the previous work, use anything I can to plant seeds in the API Commons, but then also tighten up the blog and information section. Then I’ll focus on showcasing the Spectral rules I’ve developed as part of all of the APIs.json profiling I’ve done behind APIs.io. I am using all of these rules to rate and rank the APIs I am publishing via the APIs.io search engine, powering both the local and cloud searches I mentioned above. This is API Evangelist’s commercial contribution to the commercial APIs.io search engine, but also a valuable exhaust from my work profiling Stripe, Twilio, and other top APIs that I have included in the index.

I would say that my usage of Spectral is very different from how you see it applied to govern the design of API operations. While I am also using Spectral rules to lint the surface area of APIs using their OpenAPI, I am also expanding that to lint the surface area of API operations. I am also using rules to identify patterns and anti-patterns. However, I may or may not tell you whether something is a pattern or anti-pattern, I am more interested in mining the patterns, and making them available via search. I enjoy mapping the API landscape in search of patterns more than I am enjoy telling you how to design an API or whether your OpenAPI is complete—-I will leave that to other service providers to do.

Spectral is how I identify any relevant pattern across the world of APIs. OpenAPI is how I map out each API. APIs.json is how I map out each API provider’s operation. They all work in concert to produce a by-product I am keeping for myself. This approach to mapping, but also the exhaust produced from mapping, I feel is where my little bit of value generation exists. I will use this to tell stories here on the blog. I see it as my little crystal ball regarding what is happening across the API realm. While I think the resulting APIs.io search index is valuable and important, I feel like there is even more value to be had from having a machine-readable set of patterns from across the operations of thousands of API providers.

My vision for API Evangelist reflects what it has always been, but I am hoping I can squeeze more interesting stories out of the API landscape, without having to rely on social media sources. I am looking to go directly to the source, and map things out at scale. API Evangelist will just remain where I rant and rave about what I am seeing, but I am hoping to be able to conjure up compelling stories at scale from across the API Commons.

The API Commons

I want the API Commons to be a reflection projected in front of us of the API landscape we are mapping out using APIs.json. Our goal is to produce the common schema needed to power the API economy at scale from our crawling, profiling, and indexing the API landscape. This is about turning things like Twilio’s PII OpenAPI vendor extension into a common schema that can be used to identify personally identifiable information (PII) available via APIs, and making it available as part of the API Commons.

The API Commons should be used to define and make the API landscape more discoverable. We are using APIs.json from the API Commons to profile top APIs like Twilio, Stripe, Amazon, GitHub, and others. We are making this index available publicly via GitHub, while also using it to power the APIs.io search engine. The patterns and anti-patterns of APIs and the operations surrounding them mined as part of this process is what we can use to inform the API Commons. These are the building blocks in use by API producers already, let’s further standardize and automate using these existing patterns—-contributing to more adoption, standardization and interoperability.

This post was just another one of those Saturday visions I just had to get out of my head. You can find these types of essays sprinkled across the years here on the blog. I needed to zoom out before I got to work on the API Commons website and supporting the GitHub organization. I needed to understand more about what the API Commons can be, and how APIs.json, APIs.io, and API Evangelist fit into the picture. Drawing those clear lines in the sand. There are a number of areas on this post I am already looking at expanding. I need more about projects, partners, and grants. I need to backfill more of my government work from previous rants like this one. Oh well, there is always more work. This is a good start. I feel like I can get the next version of API Commons up and running now, as I can clearly see it in my head.