Many of the enterprise groups we work with are struggling with API discovery and understanding where all the web services and web APIs exist across their internal groups.
Most groups have some sort of catalog, or discovery service in operation, depending on how far along they are in their API journey, but often, they lack the scope and dedicated resources to deliver what is needed. This leaves businesses and development groups struggling and wondering how to find existing APIs. The result is API duplication, instead of reuse across web and mobile applications serving the enterprise.
What Is API Discovery?
API discovery is not a destination, it is an ongoing aspect of API operations. It usually begins with the need to find all of the company’s digital resources and requires:
- reaching out to every group within the enterprise to ask for information on their APIs.
- aggregating all documentation and other information about where web services and web APIs are located.
- centralizing, and hopefully beginning to standardize how APIs are defined and documented so that they can be more easily included in a wider API discovery campaign.
While API discovery is occurring across an organization, known web services and APIs can be documented and included within a central catalog or search engine. There is no reason not to do this in tandem. Ideally, this is done in a standardized, machine-readable way, using API definition formats like OpenAPI (fka Swagger). Providing the technical details API consumers will need to discover, and ultimately integrate with each API.
An Ongoing Process
The profiling of each API shouldn’t end there.
An APIs.json document should also be created, profiling the other moving parts of on-boarding with an API like sign-up, licensing, plans, pricing, terms of services, and other essential building blocks of API integration.
Once you have an OpenAPI for each service, as well as an APIs.json providing more context about the groups and infrastructure surrounding an API, you have the makings of an API catalog and search index.
Having OpenAPI indexes for all API services will also allow for the delivery of consistent API documentation, code samples, tests, monitors, and other essential aspects of operating an API. You will be able to find APIs that exist, and once developers adopt an OpenAPI approach to defining their APIs, these documents can be collected, aggregated, crawled, and turned into a road map for API discovery and evolution across the enterprise.
Every enterprise should have an ONGOING API discovery effort.
Without a robust (enough) API discovery effort, an organization will never properly mature across other stops along the API lifecycle.
Discovering new APIs that may have been developed or purchased as part of ongoing development efforts across the enterprise can be done manually and automatically. Lacking an API discovery effort will make it hard to deploy, manage, secure, and support an API infrastructure at scale, making it more costly and inefficient with every API added to the enterprise stack. Working against the enterprise, and not reflecting why we do APIs in the first place, to help us efficiently manage access to our enterprise digital assets using low-cost web infrastructure.
