API proliferation is a real problem, though you plan to slowly ramp up your API development it is often the case that you have 20 to 50 to 100 APIs before you expect. This article provides a series of strategies to simplify API Discovery.

This is part one of a series on how to apply governance in API Connect. Governance is often considered a dirty word because when people imagine governance, they see red tape that stifles progress. If governance is designed properly it can provide a single approach for all parts of the project with minimal impact to the development rate.

When a consumer goes to your developer portal for the first time, they go to understand what use cases they can fulfil easily and want to explore what you offer. In API Connect we have a concept of products that contain one or more APIs. By grouping your APIs into products by use case or usage scenario you can quickly advertise to them what they can do. The objective of a product is to provide API groupings that make sense to differing consumer categories. So even though two different consumer may want to perform the same actions or access the same data, they may well be doing it for completely reasons. By exposing APIs in a more consumer centric compared to the older SOA approach of trying to find the perfect single re-usable service.

There is no requirement saying that an API can only be in a single product. Having all APIs in their own products and inversely putting all APIs in to a single product are both anti patterns. By following either of these strategies you are making the life of the consumer harder as they try to determine which APIs are required to complete a use case. In addition, managing and versioning using these approaches is significantly more challenging. By aligning your product strategy to mirror the uses cases you enable your consumers to quickly find and implement the required use cases.

The second time a consumer visits your developer portal they are viewing with a particular use case or area they need to focus in mind. In order to assist their discovery there are a few strategies that should be implemented. Every API and product - with no exception - must have a description that contains key words. This enables the APIs with specific key words to appear in search results and the consumers can clearly identify their purpose. API Connect also has a taxonomy concept called categories. Categories should be added to every API and product. The portal can filter APIs and products on Categories to quickly show subsets of APIs. For example, if you are implementing Open Banking specifications then you should categorise each API as Open Banking and with any other key words associated. The product should also be categorised as Open Banking. Data Models in each API should follow a consistent pattern where possible to assist with the consumption of the API. By using the same attributes and identifiers these can be searched to assist with the API discovery.

Ensure that a minimal number of versions of each product and API are available. My recommendation is that no more than three product versions are available for a single API product. These can be considered the latest and greatest, the superseded (previous) version and the deprecated version. For more information on versioning please read my article https://chrisphillips-cminion.github.io/apiconnect/2019/05/24/apiversioning.html . If a strict versioning system is not followed, including controlling the number of deployed versions, it is very likely the number of APIs to be managed grows far too quickly.

In this blog post we have covered ways to simplify the discovery activity for your consumers. By following this advice not only will your consumers be able to quickly find the APIs made available but also the API provider team can quickly see which APIs already exist to ensure they are not duplicating effort.