I have been defining my APIs as individual methods for some time now. Distilling down the many different paths and HTTP methods you can execute for each API provider into individual requests. I originally began doing this as a way of storing APIs in my database, but it is something that has continued because it allows me to be more precise in my API discovery efforts. You see, I rarely am searching for the Twitter API, I am usually looking for some specific capability which the Twitter API offers. Something like search for Tweet or user, or post a Tweet, or add someone to a Twitter list. The more I profile and work with APIs in this way, the more I feel like this reflects the future of API discovery, and is one of the reasons why API discovery has stagnated for so long.
In 2019, there is no really beneficial way to find APIs. Programmable is ok to a point, but usually you just end up Googling for what you need. I have thousands of APIs profiled and searchable via a database, and even my current approach is less then useful. I have the data, I just do not have the right meta data, and resulting search interface that allows me to find what I need on a daily basis. I am thinking through how I name, describe, tag, and organize the different API capability collections I’m pumping out, hoping to develop a more sophisticated way to organize them beyond just publishing to a GitHub repository. Forcing me to think a little more about the big picture of how others might find the API capabilities they need, before I finalize my approach, and possibly evolve how we define API definitions like Postman collections, and enable people to discover, organize, execute, and automate what they need to get their work done.
I was thinking more about API discovery over breakfast this morning while asking my partner in crime if she thought developing an API search engine was really needed. To which she replied, do people really search for APIs? I’d say no. There is a very small group of us who think about this all the time and regularly search for APIs. Developers will Google for an API when they have a specific need, or maybe explore one they stumble across in a blog post, Tweet, or other location, but most people will never be searching for an API. This is why traffic to most API developer portals is so low. Developers will stumble across it, sign up for a key, but will not likely come back unless they need something else. Normal people aren’t even aware this entire world exists, and will not be thinking about searching for an API when wanting to solve a problem—unless, the API solutions is described as a specific capability they are interested in.
This reality leaves most API documentation woefully inaccessible to search engines, and people looking to solve problems. Unless there is a search engine that indexes the capabilities of individual API requests and understands the semantics of what is possible, it is unlikely that an API will be found. This is what makes integration platform as a service (iPaaS) providers like IFTT, Zapier, and other so critical—if they publish menus of their API capabilities. An API capability is less about the API than it is about what it does, which can be a combination of what it does in isolation, as well as what it does paired with another API. API capabilities aren’t just about the technology of APIs, it is also about the business and politics of what our individual or organizational capabilities are, and being capable of orchestrating with our personal and professional data, content, and algorithms in the way that benefits us, and streamlines our everyday lives.
This post is all about me ideating, brainstorming, and pivoting on what I think API discovery is, and why it isn’t something we have been able to collectively solve as a community over the last decade. I’m thinking it is because us technologists are too focused on the API, and assume everyone else will care as much as we do about the granular details of what an API does. I don’t think people care about APIs. I think people care about what they do. I am not convinced that an API search engine is what is needed. I feel like this is falling into the trap of shaping my vision of the future based upon what has already happened, and missing the real way that APIs are going to be put to work in the future. I think that people aren’t interested in finding APIs, and they they are interested in finding digital capabilities that they can use on the ground within their personal and professional lives. I think a search engine of API capabilities makes more sense than a search engine for APIs, because most people don’t see an API as something that empowers them, however with a little more work, I think we can expose the value that exists and make it more discoverable and usable by average people.
This article originally appeared here.
