Designing Discoverable Event-Driven APIs For Reactive Apps
Having a discoverable API makes it easier for your users to understand and build mental models of your application. New data and relationships can be found without the user knowing of their existence. It also makes it easy to inline documentation with links to external documentation.
When designing Web APIs, many constraints and factors affect the decisions we make as software architects and developers. Some of these constraints are internal (like what tools and libraries are available within our tech stacks), and others external (like choosing a representational format easy for clients to consume, such as JSON). Regardless of the specific constraints facing each API designer, we almost universally want our Web APIs to be easy to use, flexible, and consistent. This article by Jordan Ambra does a great job of explaining these "golden rules" we all hope to follow as API designers.
The best Web APIs allow API users to use a service with minimum effort and knowledge of the system. Presenting the API user with only the information required to perform a task at hand, with links to related information that they may be interested in, allows for the user to focus on using your API to do what they need to do at the moment while having enough context to learn more about your API should the need arise. This scheme leads to APIs that are discoverable: API users can interact with your API from a single entry point in a way that requires little to no prior knowledge, and "discover" the rest of your API as needed.
Having a discoverable API makes it easier for your API users to understand, build mental models of your application and its data. New data and relationships can be found, even without the user knowing of their existence. It also makes it easy to inline documentation with links to external documentation. Client applications built on discoverable APIs have simplified logic since the responsibility of creating link URLs remains with your API, meaning as your API changes and evolves, it's easier to change your URL-structure without breaking client applications.