I am working to build out the API Gallery for Streamdata.io, profiling a wide variety of APIs for inclusion in the directory, adding to the wealth of APIs that could be streamed using the service. As I work to build the index, I’m faced with the timeless question regarding, what is an API? Not technically what an API does, but what is an API in the context of helping people discover the API they are looking for. Is Twitter an API, or is the Twitter search/tweets path an API? My answer to this question always distills down to a specific API path, or as some call it an API endpoint. Targeting a specific implementation, use case, or value generated by a single API provider.
Like most things in the API sector, words are used interchangeably, and depending on how much experience you have in the business, you will have much finer grained definitions about what something is, or isn’t. When I’m talking to the average business user, the Twitter API is the largest possible scope–the entire thing. In the context of API discovery, and helping someone find an API to stream or to solve a specific problem in their world, I’m going to resort to a very precise definition–in this case, it is the specific Twitter API path that will be needed. Depending on my audience, I will zoom out, or zoom in on what constitutes a unit of API. The only consistency I’m looking to deliver is regarding helping people understand, and find what they looking for–I’m not worried about always using the same scope in my definition of what an API is.
You can see an example of this in action with the Alpha Vantage market data API I’m currently profiling, and adding to the gallery. Is Alpha Vantage is a single API, or 24 separate APIs? In the context of the Streamdata.io API Gallery, it will be 24 separate APIs. In the context of telling the story on the blog, there is a single Alpha Vantage API, with many paths available. I don’t want someone searching specifically for a currency API to have to wade through all 24 Alpha Vantage paths, I want them to find specifically the path for their currency API. When it comes to API storytelling, I am fine with widening the scope of my definition, but when it comes to API discovery I prefer to narrow the scope down to a more granular unit of value.
For me, it all comes down the definition of what an API is. It is all about applying a programmatic interface. If I’m applying in a story that targets a business user, I can speak in general terms. If I’m applying to solve a specific business problem, I’m going to need to get more precise. This precision can spin out of control if you are dealing with developers who tend to get dogmatic about programming languages, frameworks, platforms, and the other things that make their worlds go round. I’m not in the business of being “right”. I’m in the business of helping people understand, and solve the problems they have. Which gives me a wider license when it comes to defining how big or small an API can be. It is a good place to be.
