January 2021 Summaries

API discovery is a crucial aspect of managing multiple APIs within an organization, particularly when each API is maintained by separate teams following a microservices approach. This discussion explores different methods for organizing API documentation, such as using a unified sidebar that presents all APIs in a single navigation pane, distinct sidebars for each API that provide contextual navigation, and a drilldown sidebar that offers a hybrid approach by allowing users to explore deeper levels of API documentation while maintaining a connection to the parent sidebar. Additionally, showcasing an API catalog on a landing page through tiles representing each API product and implementing a search feature within the Redocly Developer portal are highlighted as effective strategies for enhancing API discoverability. The text invites feedback on alternative approaches to API organization to better support consumer access and navigation.

In a series of posts, organizations can learn how to effectively utilize OpenAPI definitions, source control repositories, and Redocly products to enhance API documentation and development. Redocly's developer portal facilitates collaboration between developers and technical writers by providing all necessary API information, which includes guides and examples. The text outlines three approaches for managing OpenAPI definitions: co-locating them with code in a single repository, maintaining them in a separate dedicated repository, and synchronizing them between code and dedicated repositories. Each approach has its advantages and challenges; for instance, the first approach promotes synchronization with the code but may raise security concerns, while the second approach eases access for non-developers but requires manual synchronization. The third approach ensures synchronization but involves complex workflows. Redocly suggests starting with the first approach for its simplicity and ease of implementation, while the subsequent approaches cater to specific organizational needs and team dynamics. The discussion is set to continue in future posts, with a focus on implementing a two-way sync between Git repositories.