High Usage APIs and Externalizing API Metrics Within API Documentation
An API expert and researcher discusses the importance of API documentation and features that make documentation really effective.
Join the DZone community and get the full member experience.Join For Free
I am profiling a number of market data APIs as part of my research with Streamdata.io. As I work my way through the process of profiling APIs I am always looking for other interesting ideas for stories on API Evangelist. One of the things I noticed while profiling Alpha Vantage, was that they highlighted their high usage APIs with prominent, very colorful labels. One of the things I’m working to determine in this round of profiling is how “real-time” APIs are, or aren’t, and the high usage label adds another interesting dimension to this work.
While reviewing API documentation it is nice to have labels that distinguish APIs from each other. Alpha Vantage has a fairly large number of APIs so it is nice to be able to focus on the ones that are used the most and are more popular. For example, as part of my profiling, I focused on the high usage technical indicator APIs, rather than profiling all of them. I need to be able to prioritize my work, and these labels helped me do that. Providing one example of the benefit that these types of labels can bring to the table. I’m guessing that there are many other time-saving aspects of labeling popular APIs, beyond just saving me time.
This type of labeling is an interesting way of externalizing API analytics in my opinion. Which is another interesting concept to think about across API operations. How can you take the most meaningful data points across your API management processes, and distill them down, externalize and share them so that your API consumers can benefit from valuable API metrics? In this context, I could see a whole range of labels that could be established, applied to interactive documentation using OpenAPI tags, and made available across API documentation, helping make APIs even more dynamic, and in sync with how they are actually being used, measured, and making an impact on operations.
I’m a big fan of making API documentation even more interactive, alive, and meaningful to API consumers. I’m thinking that tagging and labeling are how we are going to do this in the future. Generating a very visual, but also semantic, layer of meaning that we can overlay in our API documentation, making them even more accessible by API consumers. I know that Alpha Vantage’s high usage labels have saved me significant amounts work, and I’m sure there are other approaches that could continue delivering in this way. It is something I’m keeping a close eye on this increasingly event-driven, API landscape, where API integration is becoming more dynamic and real time.
Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.