---
published: true
layout: post
title: Where Is The API Evidence?
tags:
  - Evidence
  - Artifacts
  - Discovery
  - Landscape
image: >-
  https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/good-year-home-merchandise-los-angeles-downtown-from-afar.jpg
---
I am talking with folks about the different faces of API discovery, which for me, at the intersection of governance, lifecycle, and the platform from a producer and consumer perspective across internal, 1st-party, and 3rd-party is all about finding the evidence. I’ll cite [Aidan Cunniffe](https://www.linkedin.com/in/acunniffe/) for instigating my views on API evidence, but in my endless journey searching for the API truth, I find evidence to be the most appropriate way to describe what is needed to provide meaningful API discovery solutions at the intersection of API governance, lifecycle, and the platform.

## Discovery
The discovery of APIs is a very broad topic that means many different things to different people, depending on your role, experience, and where you work. For me, API discovery is a human or automated endeavor across three high level channels.

- **Web** - Using Bing, Google, and other search APIs to find evidence of APIs.
- **Git** - Using GitHub, GitLab, Bitbucket, and the underlying git to find evidence.
- **Infra** - Taping existing infrastructure APIs in use to find evidence of APIs.

The discovery of APIs across these channels requires vocabularies, searching, crawling, and harvesting paths, schema, headers, and parameters and stitching them together into a coherent picture of what APIs exist from both the API producer and consumer levels.

## Messaging
Evidence of APIs exist as a part of conversations we have on the default channels used by an enterprise, from referencing the name of APIs, sharing the URLs, or even the pasting of parts of, or entire artifacts that are being used to produce or consume APIs.

- **Slack** - Hitting the Slack API to search and harvest signals.
- **Teams** - Hitting the Teams API to search and harvest signals.
- **Discord** - Hitting the Discord API to search and harvest signals.
- **Email** - Hitting the POP / SMTP / IMAP API to search and harvest signals.

I’d say messaging provides valuable evidence of APIs, but more importantly the people behind the work occurring to produce and consume APIs, adding a useful layer to the evidence that bridges from the technical side of discovery into the business side of things.

<img src="https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/good-year-home-merchandise-city-skyline-grey.jpg" style="padding: 15px;">

## Manual
Even with what you can automate with finding evidence of APIs, in my experience you still need humans to be part of the equation and you should be using bookmarklets and buttons to help find evidence of APIs in use across operations anywhere humans frequent.

- **Bookmarklets** - Targeted browser bookmarklets to identify evidence type and location.
- **Buttons** - Fork, run, and other semantic buttons that take actions and provide evidence.

In my opinion, everyone at a company should be conscripted to aid in the reporting of API evidence and be rewarded for their work, providing simple buttons and bookmarklets they can click in different scenarios to make API operations more visible as part of API governance efforts.

## Artifacts
With automated discovery, messaging, and human labor tapped, there are a number of artifacts that I am currently accepting as evidence of APIs and parsing to understand what the evidence means and how it can be used in a much larger map of API operations.

- **HTML** - Harvest portal, wiki, and other documentation pages for evidence.
- **APIs.json** - Harvest APIs.json artifacts in use to define API operations.
- **OpenAPI** - Harvest the OpenAPI artifacts to define individual Apis.
- **JSON Schema** - Finding all of the schema being applied across APIs.
- **Postman Collections** - Looking for any Postman collections in use.
- **Bruno Collections** - Looking for any Bruno collections in use.

I have a much longer list, but I am starting here to stitch together my API landscape map for any given domain, harvesting all of the paths, parameters, header, schema, and operational or platform signals I can get my hands-on, until a coherent picture of a domain comes into picture.

<img src="https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/good-year-home-merchandise-nyc-skyline-from-ferry.jpg" style="padding: 15px;">

## Humans
Evidence isn’t limited to APIs and the technical bits, the human, team, expert, champion, and leaders who make up the human landscape are important to harvest, finding the evidence of teams who are doing the work and caring about both the technical and business details of API operations.

- **Consumers** - Who are the people that are consuming APIs.
- **Teams** - Who are the teams that are producing APIs.
- **Champions** - Who stands out as a champion for APIs.
- **Leaders** - Who is in a leadership role and talking Apis.

Evidence of humans doing APIs, and talking to those humans is an important aspect of API discovery, governance, and platform, because it is the evangelism and relationship building that is needed beyond the APIs.json, OpenAPI, JSON Schema, and other bits that are being governed by Spectral.

## API Discovery
This is a much different conversation about API discovery than most people will be familiar with. I am looking for evidence of APIs to stitch together into a search index that can be used to not only discover APIs, but also govern and strengthen the API platform.  This is an automated and manual API discovery that should be happening 24/7. This is how you map the sprawling chaotic API landscape across the open web, an industry, or within a specific enterprise. This is what I am doing to build my APIs.io index, but also to map the API patterns and anti-patterns that exist across any domain. 

In my experience there is no single source of truth for an API, but gathering evidence from across many channels allows you to confidently squint in any given moment and feel like you have the source of truth. Or at least that is the intent. I have all areas of this implemented except for the messaging piece. This will come next. Right now I am just looking to turn up the volume on the evidence gathering for APIs. Once I have the artifacts gathered and assembled, there is always the last mile of metadata and other refinement that has to occur. I just wanted to capture my thoughts on what evidence matters in this moment, and set the stage for what is next, while I also streamline and automate the metadata and refinement of the source of truth for top APIs across industries at scale.