The personal website of @erikwittern

API Harmony Hits the Next Major Version

January 20th 2017
Originally published at:

Happy new year! API Harmony has reached a new major version. The completely redesigned UI helps developers find, learn about, and use APIs by presenting actionable data in unprecedented quality and quantity. A streamlined architecture improves API Harmony's deployment and operations, in its current and novel contexts.

We're excited to share with you some important information regarding the latest release of API Harmony. The team has been hard at work listening to clients, users and the community at large to find the right direction to provide the most benefit to enterprise developers looking to consume REST APIs.

The general strategy of the revised UI is to take complete advantage of the OpenAPI Specification format and dive deeper into providing actionable information for the enterprise developer.

Main new Features

There are some user-facing changes in the new API Harmony:

  • Focus on lessons learned and code snippets - The revised API Harmony UI centers around the endpoints of an API. Usage counts are now presented for individual endpoints and aggregations of them, allowing developers to easily understand which parts of an API likely matter the most. Per endpoint, detailed information about lessons learned on parameters and response data usage is provided.

Figure 1: Screenshot of the new APIs details page, showing usage counts and lessons learnedFigure 1: Screenshot of the new APIs details page, showing usage counts and lessons learned

  • Enhanced data The new UI is the first to present the full extend of our latest mined API data. This dataset represents both the highest quality as well as the most comprehensive that has been shared to date, having been most notably extended with regard to the lessons learned mined from open source projects that use web APIs.

  • OpenAPI-based data model As part of IBM's participation in the Open API Initiative we have changed API Harmony's underlying data model to be centered around the OpenAPI Specification. This opens many doors as it provide for a common format for systems to exchange API specifications. It also means that existing specifications can directly be fed into API Harmony. And users can directly access the Open API Specifications driving the UI.

  • New relationship analysis We revised the relationship graph of API Harmony to now focus solely on which APIs have been used together. The graph shows up to 15 of the APIs that have most commonly been used together with the current one. Clicking on an edge in the graph shows the GitHub repositories that use the APIs together. If more than 15 APIs are related to the current one, a list can be displayed to show them.

Figure 2: Screenshot of the revised API relationship graphFigure 2: Screenshot of the revised API relationship graph

Architectural Changes

Beyond these user-facing features, we also reworked the architecture of the system with the following goals:

  • Extensibility We believe going forward that there will be more and more channels necessary to support the optimal developer experience. For example, our experiments with IDE integration and chat bot support are both interested methods to engage the developer in unobtrusive ways. The new backend allows us to more easily build out these capabilities.

  • Lightweight, embeddable UI We've refined the approach to deliver the UI experience to make it easier to deploy within an enterprise context as well as to embed the capabilities of API Harmony within a provider's documentation - the API details page (including endpoint data like code snippets etc.) can now be deployed as a stand-alone module.

  • Simplified operations We have simplified the architecture in API Harmony to decrease efforts for deployment and operation, and thus make it easier to use API Harmony in different contexts in the future.

These changes are now reflected in API Harmony. As always, we are excited to hear your feedback on Twitter @apiHarmony.