Do You Know Where All Your APIs Are?

We are consulting with more banks, insurance providers, and other financial companies around their API life cycle, and API governance practices. We aren’t just in the business of selling companies streaming services for their existing APIs, we are also in the business of helping companies make sure they have simple, high value APIs available to stream. As we begin new engagements with companies, one of the things we ask is, “where are all of your APIs?” More often than not, companies replay nervously with, “we do not know.”

“Teams are busy. Organizations are large. Things get lost in the shuffle and hustle.”

It is extremely common for large organizations to be operating APIs in the service of web, mobile, and device based applications, without a common directory or catalog of every API that exists. Developers from different groups deliver APIs in response to specific projects, and never publish, share, and make known that these APIs exist outside their groups. Teams are busy. Organizations are large. Things get lost in the shuffle and hustle. While we might be a little embarrassed that this is the state of things, we should quickly get over it and begin the hard work of discovering, cataloging, and maintain an up to date map of where all of our APIs are, so that when a partner visits, you can quickly pull out the map and point to where the relevant API resources are.

To help move forward the conversations we are having with our consulting partners, one of the first tasks we find ourselves helping with is mapping out where all of the APIs are. Working with existing stakeholders, and team members to document what APIs are already in use, or are being developed. Providing a simple index of APIs and other web services that exist across an organization. While we usually begin working within a simple Google or shared Word document, listing out the name of the APIs, and who is the owner, we usually quickly get to where we are actually documenting each individual API using the OpenAPI specification. Providing not just a title, description, and some tags for each API, but an actual machine readable definition of what it can do.

“We know that you are having painful conversations regarding where your APIs are”

As we evolve beyond a single document, we usually begin publishing a machine readable index using Github, Gitlab, Bitbucket, or other continuously integrated and deployed solution. Allowing the API map to be integrated into existing pipelines and workflows. API maps will never just be a static thing, that is considered complete. It will be a living, dynamic, evolving map that will be shifting as the API landscape evolves across an organization. Ideally, it is a federated directory of maps, owned by each team, with a common strategy for making accessible, keeping updated, and reporting upon across disparate groups. One API or service directory to rule them all often fails, and falls into disrepair, where local ownership, as part of a larger strategy tends to do much better in the long run.

Do you know where all your APIs are? We’d love to help you map out the private, partner, and public API landscape at your organization. We know that you are having painful conversations regarding where your APIs are internally between groups, and externally every time you bring on a new partner or agency to help you with a project. You really should have a map in place to help your team navigate the API landscape within your company, organization, institution, or government agency. Feel free to reach out, we are happy to help you shift the state of things when it comes to API discovery, and begin to map out the known APIs, as well as the unknown APIs hiding in the shadows behind web, mobile, and device applications.