Publishing an API does not require a lot of work, but it is a big milestone in the lifecycle of the API. From an organizational perspective, the responsibility of the API is transferred from the development unit to the operations unit. But most importantly, the API and its documentation become publicly available, API consumers will start building API clients and start using the API.
Publishing the API also means freezing its interface specification. After publishing, there is no agility in the development process any longer. Changes on published APIs require a traditional change management process.
For each published API, the API provider has an implicit contract with all its API consumers, which states the interface of the API. This is why once an API gets published, its interface can never change and the API needs to be maintained for a long time. Publishing an API implies a long-term commitment for maintaining it.
Publishing an API requires an appropriate documentation for consumers. It almost goes without saying that the documentation needs to be consistent with the implementation. Sometimes, however, the problem is that the implementation gets changed during maintenance or redesign, but the documentation is not updated. This can be avoided by generating both the implementation skeleton and the documentation from the same single source of truth, from the API description.
Verification: Study Metrics, Reports and Logs
It is the expectation for a published API that an increasing number of consumers successfully use the API. To be able to find out if and how this expectation is actually fulfilled by the API, usage of the API has to be monitored, measured and analyzed. Some of the metrics, which might be interesting in this context are: the total number of API calls per time frame, the number of API calls per consumer, and how many API calls resulted in an error vs in success. Not only quantitative analysis is relevant, but also some qualitative analysis.
Qualitative analysis includes for example understanding and categorizing the solutions, which the API consumers build with the API. An API provider would like to discover if API consumers use the API as intended or if they use the API in new ways that were never imagined by the API provider at the outset. Which of the usage scenarios were correctly predicted and which new usage scenarios evolved? This can also be a trigger point to find out if a new version of the API is needed and to determine if it needs to be redesigned.
For a quantitative analysis, the first step is to determine the usage of the API. The second step is to determine how successful the API is in contributing to the API solution. The third step is to draw conclusions, discover patterns in the usage, compare all the APIs in the portfolio. A relevant metric is the number successful API calls, especially if compared to the number of unsuccessful API calls. Do some API consumers have trouble getting the API to work as intended? Are there lots of error messages? Analyses according to this metric could be a trigger for updating the API documentation or redesigning the API.
Metrics are not only interesting to the API provider, but also to the API consumers. They are interested in API analytics, dashboards, reports and monitoring. The performance and availability metrics such as status reports, up-time and response time should not only be available to the API provider, but also to the API consumers.
The API provider needs to continuously evaluate if the business objectives are met and if the business objectives are still up to date. Metrics allow for calculating business value and the ROI for the API provider. Metrics allow for understanding the consumers and marketing to them better. Based on the feedback gained and the insights obtained from analytics, the provider can improve the API.
Metrics based on consumer behavior are the real feedback for the success of the API. They allow for measuring if the adoption is as expected and if the revenue is as expected. Even for successful APIs, the business or market might change and require a review if the API is still adequate for the market as it is today.