The API landscape within any enterprise organization is ever changing and evolving, and with APIs being such an abstract and often undocumented aspects of organization work, it can be very difficult to “see” APIs, let alone the forward motion and change of our API infrastructure. As much as we’d love for our teams to properly document all APIs used to power web, mobile, device, and network APIs we depend upon and iterate upon each day, the reality is that APIs regularly possess paths, parameters, schema, and other properties that aren’t always well documented and made “visible” as part of the API development process. This ever expanding shadow landscape of our enterprise API operations is being heavily invested in across a variety of API service providers.

However, we currently lack an effective way to define and communicate change across our APIs using the API contracts we use to collaborate and guide APIs across the API lifecycle. You can version each API within our machine readable API contracts, but we cannot effectively trach change across many files, and many APIs. Hopefully this is an areas we’ll see more movement as there are numerous very smart people working on this problem.