This is the first article in a two-part series focused on API documentation and discoverability
The API developer experience
APIs are no longer treated as solely an integration technology but are also viewed as software products that can empower an organization with modern digital business channels and additional revenue opportunities. The most forward-looking and savvy development teams are building reusable APIs that can increase the development speed across an entire organization, enabling a quicker go-to-market and fostering a culture of innovation.
Often, a lot of blood, sweat, and tears go into the API development process. But once the APIs are developed, the developer needs to remove their ‘developer’ hat and think like an API consumer to create a consumer-centric ‘API developer experience.’ An ideal API developer experience caters to both technical and business audiences, enabling them to discover and consume the APIs effortlessly.
The most important factors that contribute to the API developer experience are: API discoverability and API documentation.
In this part of the two-part series blog, we will focus on how to make APIs truly discoverable using Anypoint Exchange, enabling broader consumption.
Enabling API discoverability
Google has set high standards when it comes to search, so much so that it has become a herculean task for other companies to develop their own built-in search experience. Many API sites don’t have robust and comprehensive search engines in the first place, thus making it difficult for consumers to find the right APIs.
Using Anypoint Exchange to publish your APIs makes it just as easy to discover your APIs. It lays out comprehensive search and filter features. The MuleSoft team responsible for Anypoint Exchange makes a constant effort to improve the search experience for its users.
Here are the five Exchange tools that make your APIs truly discoverable:
#1 Search
Exchange search enables its users to find APIs and other assets housed within Exchange. When a user searches for a specific string, Exchange expands that search term and looks for matches in:
- API name and description
- Markdown content in the API documentation
- Tags
- Categories
- Custom fields
- Properties within API specifications (base URL, method, traits, endpoints, etc.)
Exchange search also provides insights to the users on ‘match criteria,’ which highlights why an API is being shown in the search results.
This comprehensive search hits the bullseye when it comes to returning the right API results to the consumer.
#2 Filters
Exchange also provides an advanced and dynamic filter solution that can narrow down the search results to the most relevant API assets. Exchange now offers a total of four filters that can be applied to the search term.
Below are the available filters:
- Type: Allows users to filter on type of an API or asset, for example, Rest API, SOAP API, Connector, etc.
- Organization: Allows users to filter the APIs based on which organization or business group an API belongs to.
- Category: Allows users to filter APIs based on their categorization.
- Tags: Allows users to filter on tags added to API versions.
#3 Save searches
As organizations grow, so does its application network. An organization’s Exchange administrators can leverage this feature to save the most common search and filter combinations for everyone in their organization to use as saved searches. This makes it easier for consumers to discover the APIs and accelerate their development process.
#4 Categories
Exchange provides categorization settings for APIs that can be grouped into categories. This allows consumers to filter on a specific category of interest and find the relevant set of APIs.
Categories of APIs and assets can be customized per your organization’s needs and ambience. Some of the common categories and the values that can be created are as below:
- API layer: system, process, or experience
- Application systems: Salesforce, SAP, database, etc.
- Social: Facebook, Twitter, Instagram, etc.
#5 Tags
Additionally, by using the tags feature, organizations can label their APIs to further drive the discovery and consumption of assets. Applying multiple tags to an API is a best practice when dealing with complex or broad-use applications. For example, when a Salesforce system API is tagged with sfdc and system-api, a consumer looking for a similar API can simply discover it using any of these filters.
Conclusion
Imagine going to a large grocery store that has no aisle signs or descriptions. It would be an absolute nightmare to shop and find the things you are looking for. Similarly, API consumers can feel lost without good API discoverability practices. The built-in Exchange search experience combined with diligent utilization of categories and tags goes a long way in providing superior API developer experience.
If you would like to learn more about how to create next-level API consumer experiences and achieve great API documentation with Anypoint Exchange please watch my Friends of Max video below and stay tuned for my next blog entry.
For more information on how to get developers quick API access in an easy-to-navigate portal, check out our training course Anypoint Platform: API Design.
