{"API Evangelist"}

An API Has No Value Until It Is Actually Used

I am putting a lot of thought into the value of an API request and response lately. I've talked about the potential of a Postman collection as a unit of measurement, for the API economy. I’m also spending time breaking down the monetization strategies of the 700+ companies I track on, but I’m really looking to get beyond just the API pricing, and actually measure any evidence of real value that I can.

This particular post is born out of a conversation with John Sheehan (@johnsheehan), CEO of Runscope, while we were in Sydney Australia last month for API Days Sydney. John had mentioned that when people asked him which are the best APIs out there, he replies “none of them, until they are used”. Which when you think about it, it really is the truth--APIs do not offer ay value, until they are actually put to use in an app, or system integration.

It is easy to place the value in the actual API definition, or in the request, or response from the API. There is also a lot of talk about much of the value being in the documentation, or possibly the SDK. You can event point to the value being that it is a public API, with easy on-boarding, that you can rely on, and scale as you need. All of this may contribute units to the overall value, but at this point any API still doesn't have value to anyone.

As John says, the point at which an API has value, is when it is used. Until that point, an API isn’t a thing. I’m not saying the API call as a metric, is the single metric to rule them all, but it is at this point when I feel you can really begin to measure the value an API delivers, and capture the exhaust from it. Honestly, I don’t know what I mean by all of this, it really is just an exercise for me to break down the moving parts of each API, so that I can better understand how APIs will potentially fuel the API economy--think what Runscope does, but for the monetization portion of each API transaction.

APIs.json As A Distributed Transport Layer For The API Economy

I'm working with multiple partners to define what I’d consider to be the firsts stops along the API lifecycle, when you use APIs.json as the scaffolding for your API operations. APIs.json is a machine readable format for indexing APIs, that exist under a specific website domain, or are part of a aggregate collection designed for a specific project or objective.

To help me, and the folks I’m working with to better see the API lifecycle that APIs.json is enabling, I wanted to take a stroll through each of the stops along the API lifecycle, and think through the potential for additional formats, services, and tooling throughout the entire journey. I want to explore the possibilities for individual API providers, API consumers, as well as API service providers, and the aggregate level, where companies and individuals are delivering valuable tools and services to the overall space.

First, lets start with what I envision APIs.json enabling at the direct one to one, API provider and consumer levels:

  • API Metadata - Quick access to the most important info about any API, its title, description, image, endpoint, url and tags.
  • API Surface Area - (The Truth) - Using Swagger and API Blueprint, any developer can quickly quantify the surface area of an API or microservice.
  • Execute API - Include Postman Collections, allowing each API to be execute ready, allowing consumers to load in Postman and deliver the value behind any API.
  • On-Board API - One click reference to where an API consumer can onboard with an API.
  • Existing Server-Side Code - Locating of existing server-side code in multiple languages.
  • Auto Generate Server-Side Code - Locating of services for generating of server-side code in multiple languages.
  • Supporting Container Images - Where Docker, and other container images reside, providing instant deployment opportunities.
  • Existing Client Side Code - Locating of existing client-side code in multiple languages.
  • Auto-generate Client Side Code - Locating of services for generating of client-side code in multiple language.
  • API Pricing - Understand pricing, access tiers, and partnership opportunities around API operations.
  • Terms of Services - Access, and make sense of terms of services that apply to API usage.
  • Licensing - Understand the licensing of an API, data, content, and code related with an API.
  • General Questions - Be able to ask, and get answers to common questions about any API.
  • API Conversations - Understand where to engage in conversations, and experience streams from common sources like Github and forums.
  • Augment APIs - Add endpoints, verbs, and parameters to existing endpoints, augmenting what any single API provider can deliver.
  • API Presets - Establish preset value for API entries, allowing the single, or bulk publishing of data, content and other values to APIs.
  • API Mapping and Domain Specific Language (DSL) - Bridging API definitions, and APIs, providing much needed aggregation and reciprocity for APIs.
  • API Sandboxes - Establish API sandboxes, based upon existing API designs, allowing developers to develop against alternative API than a production environment.
  • API Simulations - Beyond just a sandbox, actually establish alternative APIs that provide specific simulations of production scenarios that an API would serve.
  • API Cookbooks - Assemble API cookbooks that help onboard API consumers using wizards, blueprints, and other established orchestration patterns.
  • API Testing - Initiate API testing tools and services, covering surface area of each API.
  • API Monitoring - Initiate API monitoring tools and services, covering surface area of each API.
  • Audit Security - Audit surface area of any API that is indexed using APIs.json.
  • API Adjacent Monitoring - Initiate monitoring of other API adjacent resources like documentation, terms of services, and other essential building blocks of operations.
  • Visualize API Surface Area - Simple, embeddable visualizations that help us see the surface area an API provides.
  • Visualize API Resources - Simple, embeddable visualizations that help us interact with the resources APIs deliver.
  • Analyze API Surface Area - Simple, plug and plug tooling and services for analyzing the surface area of any API.
  • Analyze API Resources - Simple, plug and play tooling and services for analyzing the resources APIs deliver.
  • Load API Response In Spreadsheet - Resource for loading, and importing API resources into an Excel or Google Spreadsheet.
  • Craft experiences - Weave together experiences made up of multiple API resources, and the resources that are available to support them.

This list represents my master vision for stops along the API lifecycle, that could be served via APIs.json, providing value directly to API providers, and their consumers. Each of these areas would benefit both sides of the API coin, but as you can see will add value to the APIs.json engine, in a way that goes well beyond just API discovery--which APIs.json is known for.

It is hard for me to articulate, and map out the opportunities that will be available when APIs.json is fully realized. Our goal is to push the number of APIs.json files available to a critical point, where this full lifecycle vision is a reality. Once this occurs, I see another plane of existence emerging, one that can be applied across hundreds, or thousands or public or private APIs and micro services.

Once a critical mass with the number of APIs.json files is achieved, the wider opportunities for expansion, growth, and monetization will span three main areas in my mind:

  • API Definitions - Additional API definitions like Swagger, API Blueprint, and API Commons, providing machine readable access to vital components of API operations, that can be baked into the overall API lifecycle.
    • API Pricing - A machine readable format for breaking down pricing, access tiers, and partnership opportunities around APis indexed with APIs.json.
    • API Questions - A machine readable format for aggregating questions around API operations, including terms of service, privacy policy, and other elements that impact API integration.
    • API Conversations - A machine readable for for aggregating conversations that occur around API operations, that occur on multiple channels like Github, Stack Overflow, Twitter and more.
  • API Services - The opportunity for new API services to be developed on top of the APIs.json lifecycle.
    • Testing - Introduction of testing related services to known, and custom APIs definitions.
    • Monitoring - One time and schedule monitoring services, triggered via APIs.json indexing.
    • Security - Scanning of entire API surface area defined by an APIs.json definition.
    • Broker - Use of APIs.json in API broker related activity, crafting custom API backends and stacks.
    • Analyst - Delivery of vital industry and area data and content, using APis.json format, connecting analysis directly to sources.
  • API Tooling - The opportunity for new API tooling to be developed on top of the APIs.json lifecycle.
    • Search - Continued growth in the number of API search engines like APIs.io, providing options, and competition.
    • Collections - Establishment of common tooling for doing API roundups, collections, stacks, or any other grouping that is defined.
    • Notebook - Deployment of tools for saving, organizing, and remixing using APIs.json formats, either publicly or privately.
    • Spots / Hubs - Deployment of API spots and hubs that allow aggregation of API definitions, supporting building blocks, and API consumers in a wide variety of API areas.
    • Dashboards - Deployment of dynamic, APIs.json driven dashboards that generate visualizations, listings, and other detail via machine readable API definition formats.
    • Infographics / Reports - Deployment of dynamic, APIs.json driven infographics, reports that generate visualizations, listings, and other detail via machine readable API definition formats, in a portable format.

That is just a sampling of the definition, services, and tooling opportunities that are already, and will eventually emerge around an APIs.json driven lifecycle. The objective of this post was to flush out my ideas around the one to one, and the wider API economy opportunities using in APIs.json driven API lifecycle, for my own purposes, but also to communicate my thoughts to a handful of partners who are executing definitions, services, and tooling already.

If you are curious about what this all means, and get more clarification about how your company, its services and tooling fit into this, feel free to reach out, and I’ll do what I can to help you understand where you fit. Some of the stops along this API driven supply chain, I’m depending on existing efforts like Swagger and API Blueprint to execute, some of the areas I’m pushing forward myself like API Commons, API Pricing, API Questions, and API Conversations, while other areas I’m depending on 3rd party individuals and companies to step up and own. If you think you might be interested in delivering an API definition, service, or tooling somewhere in the areas I’ve defined, feel free to reach out.

This post is a product of several conversations I’m having with folks, and the regular conversations that Steve Willmott (@njyx) of 3Scale, and I are having around the APIs.json format. Additionally we are currently working on the roadmap for APIs.io with Nicolas Grenie (@picsoung), which is the first of many tools that are being built on the APIs.json format. You can influence the roadmap for APIs.json via the Github repo, and the individual communities of each of the sub APIs.json API definitions formats like Swagger, API Blueprint, API Commons, on their own working sites and repos.

If you made it this far, thanks for listening! ;-)

What We Do In The API Community Influences How The Rest of The World Is Making Change

I was just talking with my friend Oliver Seiler (@0seiler) in New Zealand via email. Oliver is great at keeping me in tune with API related stories out of New Zealand. I was making sure he knew how much I appreciate people like him sending me regular updates, and that it is what makes API Evangelist go around—to which he replied, reminding of how important the work we are doing here in the US API space.

Oliver told me what I hear a lot, "We still need to sell our story every single day and you wouldn't believe how much anything that comes from particularly you and 18F, but also ProgrammableWeb and GDS in the UK matters to our work." This isn't an isolated case, I hear this a lot from people I talk to in government, enterprises, and other institutions around then globe--the stories we tell are used to make change in how they think and potentially operate. Our stories from the trenches, become the stories they use to sell APis to their bosses. 

These reminders are what keeps me going after almost five years of evangelizing. The stories we are sharing about API best practices, and the challenges we face across API design, deployment, management, monetization, evangelism, discovery, and integration, are important to not just the health of the overall API space, but to each public and private sectors that APIs are touching in 2015.

The message for me here, is that we all need to keep pushing forward, but also making sure we tell the stories publicly, sharing our knowledge in real-time, because people are watching, and depending on us to help influence how things work in their businesses, institutions, and government agencies around the world. #NoPressure

The API Journey: We Do Not Always Get Our API Strategy 100% Perfect, But We Can Communicate, Learn and Evolve

Running the perfect API operation is pretty much a delusional dream. Even leaders like Twilio and AWS have platform-, and ecosystem-produced problems on a regular basis. In my opinion, API are all about the journey, and while we may never get our strategy 100% perfect, we can communicate, and evolve along the way—this is what I consider the API journey.

To help demonstrate this in action, here is a post from the GSA, about the SAM API, on the US Government API Forum:

We've, rightfully, heard complaints about the SAM API languishing and the documentation not being as functional as it needs to be. We want to make sure users of the API feel comfortable using it to build real applications off of. We've adjusted how we're staffing the API as well as raised the priority the API in the eyes of our developers.

To you, this means this: 

1) At a minimum, we're sweeping through new GitHub issues weekly, but we will do everything to go through those issues more rapidly.
2) We're going to increase our transparency by making sure that anything in our backlog that's API-related is in a GitHub issue - if it's prioritized with a date, that'll be made clear, too. We want to make sure you know what's coming and on what days - and the docs will be updated to reflect what's currently implemented and what's coming.
3) We're going to publish our version management plan to the SAM API site so it's more clear what's going to cause a version change. One of the things about the SAM data is that regulations may change our data, so we should be treating some of it (like reps and certs) as variable-length instead of fixed to keep systems from breaking, so we absolutely document that.

We've already added some updates that include reference data that wasn't available before and a few minor cleanups. Expect the more as we ramp up our people at this to be worked through by the end of next week. We appreciate being held to task on this - IAE's larger strategy relies on usable, exciting APIs and we can't do that if we aren't serving you.

This is why I prescribe APIs, not because APIs are a technological wonder that magically fixes everything (they do, oh they do). I prescribe APIs because of the API journey, and if done right, the API provider can change, evolve, and learn to better serve their consumers, and in this case constituents.

APIs are born out of breaking down legacy walls built up between IT and business operations, but they have also become about breaking down walls built up between inside the firewall, and outside the firewall. In the end I do not think APIs are the thing that will change government or companies, it is the process of doing them, learning to open up and communicate, that will move the needle forward.

Something that will not happen at your agency, organization, institution, or business if you do not start on the API journey yourself.

More Pondering On My Own Microservice Definition

Like API, the term microservice has emerged as a force, along with a meaning that is very precise, or very broad, depending on who you are. The only thing I’m sure of at this point, is the term microservice is very personal, and means very different things to different people, depending on where you stand in the industry.

Regardless I can't help but consider the implications of the term, internalize it, and see what value I can derive from its meaning in my own world. This exercise leaves me asking, what is a microservice? Over and over, acknowledging I may never fully know the meaning, and like API it will be more of a journey, then it never will be a destination.

First and foremost in my world a microservice means simple, and small. Simple and small. Simple and small. Say it until you can feel it, all Buddhist colliding with API Evangelist. Simple and small, penetrates all layer of meaning for me.

  • minimal surface
  • minimal on disk
  • minimal compute
  • minimal message
  • minimal network
  • minimal ui
  • minimal time to rebuild
  • minimal time to throw away

Ultimately I want all of this, coupled with the ability to achieve maximum scale, with minimum effort. I want to do one thing, as well as I possibly can, with as minimal resources necessary, but delivering the maximum value at any scale—with value benefiting myself, my API consumers, and the end-users being served, equally.

None of this is set in stone for me. I acknowledge this is my own perception, and that others will see microservices as something entirely different. Even so, I share my definition publicly, as also I enjoy reading others definition. I kind of think that is part of the whole microservices thing, sharing your own personal definition. In reality microservices do not change my API mission, but it does allow the conversation to be distilled down, for a new generation of business leaders working to make sense of all of this.