Skip to content

Latest commit

 

History

History
32 lines (25 loc) · 4.41 KB

discoverability.md

File metadata and controls

32 lines (25 loc) · 4.41 KB
Raw

Discoverability

API discovery is about being able to find and see your API resources and capabilities whenever you need them, whether it is before you begin developing a new API, developing a web, mobile, or device application, and properly route traffic and deliver reliable applications and integrations. Ensuring you know where all your digital resources and capabilities are, so they can be secured and put to work as needed.

Components

Making API operations more discoverable is the top challenge enterprises face today. Too many make API documentation the only discoverable element. For any kind of API–private, partner, or public–teams, tests, and essential building blocks of APIs operations should be discoverable by default. The elements below represent the points of collaboration that matter most to API-first transformation.

  • Domains - Make sure domains are discoverable, allowing business and technical leadership to find everything they need for single or multiple domains.
  • Teams - Ensure that the teams behind APIs are discoverable, allowing consumers and other stakeholders to see the humans behind the operation and support for each API.
  • APIs - API discovery means making available all the artifacts that define each API, allowing those with access to search for contracts and other machine- readable definitions.
  • Documentation - Requireall APIs to have up-to-date documentation that is indexed and has visibility matching the needs of targeted private or public API consumers.
  • Mock Servers - Provide a sandbox and specific business use case mock servers for your APIs, making it easy for users to onboard without having to authenticate or sign up.
  • Tests - Reliable APIs provide access to tests, including contract, performance, security, governance, and other types you run against an API, providing transparency and building trust.
  • Environments - Publish machine-readable environments for the development, sandbox, staging, and production phases, keeping configuration variables discoverable.

This indexing of API operations becomes the institutional memory of the enterprise, providing an ongoing map of operations. Digital indexes possess everything you need to demonstrate the value an enterprise produces each day. They represent the digital resources and capabilities an enterprise has at its disposal.

API discovery isn’t just about helping consumers find the APIs they need It is about ensuring that your API operations are discoverable. It isn’t enough to provide API documentation through your developer portal.You need to ensure that all APIs and their documentation, mock servers, tests, environments, and every other aspect of your operations can be found.

State

APIs are very digital and abstract, making them difficult to “see.” Providing discoverability of APIs and the operations around them help prevent the APIs from operating in the shadows of applications.

  • Latest - Show the latest goings-n across operations, helping to surface interesting and relevant APIs and ongoing API work across domains and teams.

  • Activity - Show the configurations and changes are made across API operations, revealing what team members are doing in real time across workspaces.

  • Search - Provide a universal search for internal and external APIs that people can use to build applications, use in integrations, and develop automations.

  • Browse - Make API operations browsable by, workspace and other metadata, helping teams explore operations.

  • Notifications - Push notifications to team members and consumers, sending them useful information via native, email, and other channels.

  • Suggested - Provide suggestions for teams and consumers for relevant APIs, automations, and other resources and capabilities that might meet their needs.

  • Feedback - Allow stakeholders to provide feedback about API operations and how they are used in applications. That will give your teams ideas for possible enhancements. API discovery must keep up with the pace of business, which means that everything must be indexed natively as part of the underlying API platform.

While each API has its own API discovery considerations, this blueprint is about discoverability across all your APIs It’s important to make discovery a default state that doesn’t require additional work by teams and is able to keep pace with change as it occurs.Expanding on which elements are discoverable null