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 group shave some sort of catalog, or discovery service in operation, depending on how far along they are in their API journey, but often times they lack the scope and dedicated resources to deliver what is needed. Leaving business, as well as development groups struggling with how to find existing APIs, resulting in API duplication, instead of reuse across web, and mobile applications serving the enterprise.
API discovery is not a destination, it is an ongoing aspect of API operations. It usually begins with the need to find all of a companies digital resources, and will require reaching out to every group within the enterprise to take 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 begin to be documented and included with a central catalog or search engine–there is no reason to not do 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. 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 services, 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. Most importantly you will be able to find APIs that exist, and once developers begin to 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 organization should have an active API discovery effort occurring in an ongoing way. Manually, and automatically discovering any potentially new APIs that may have been developed or purchased as part of ongoing development efforts across the enterprise. Without a robust (enough) API discovery effort, an organization will never properly mature across other stops along the API life cycle. Making it hard to deploy, management, secure, and support 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.