If you tune into my storytelling, you’ll hear me say this a lot—-APIs are hard to see. Any API, but more importantly, legacy APIs are just really hard to see. As a result, it is very difficult to quantify the technical debt that is accumulating across the enterprise. None of the enterprises I talk to know where all of their APIs are, and the older the API is, the higher the chance the API doesn’t have up-to–date documentation, artifacts, and other things that help us see the surface area of an API, let alone understand its state. While I am a big proponent of documentation of all APIs, I am also a big fan of investing the time to document legacy APIs to help better articulate the technical debt that exists across operations across teams and with leadership.
One reason I adopted the name API Evangelist for this blog was to be theatrical and stand out. I learned early on the power of not just storytelling, but theatrical storytelling and performances. When it comes to highlighting technical debt in the form of legacy APIs, I strongly recommend investing in documentation for these APIs, but if possible, go further.
- Documentation - Makes sure that all of your legacy APIs have documentation, providing human-readable documentation for the entire surface area, ensuring anyone can “see” the API.
- Discovery - Ensuring that all legacy API are discoverable. Register them with portals, and list and feature them anywhere you can to help increase their visibility as legacy infrastructure.
- Dependencies - Connect the dots between legacy APIs, and the other services, APIs, and applications that are dependent on legacy infrastructure, articulating the full scope of each API.
- Visuals - Produce charts, graphs, landscape maps, and any other visual you can to show the scope of legacy APIs that exist, emphasizing technical debt that exists across operations.
- Usage - Make sure usage reports for all legacy APIs are accurate, up-to-date, and actively shared with leadership and cross teams, helping cultivate awareness across operations.
- Vision - Take the time to craft a narrative about what is next for each API, what could be done to improve, evolve, or replace legacy API infrastructure, and keep readily available to share.
APIs are hard to see. We also like to easily forget the APIs we’ve already built. The longer APIs are in production, the more invisible they tend to become. If legacy APIs are making you nervous or actively contributing to outages or breaches, then shine the light on them. Make sure they are seen. Ensure that anytime you have an audience with leadership that you have an up-to-date list of the legacy APIs you want to see evolved or invested in. If you can’t prioritize time to move APIs forward, at least make sure you are documenting and making legacy APIs more visible, so when the time comes, and leadership is in the mood for listening, you have what you need to convince them to invest.
Remember, on the ground floor of API operations you tend to be hyper aware of where all the technical debt resides, but other teams, and leadership isn’t always as aware as you are. In the same way you have to evangelize and market your new partner and public APIs, your legacy APIs need an ongoing evangelist effort to help keep attention on them. The more leadership will hear you talking about this technical debt, the more aware of it they will be. Eventually, they will have to give in and let your team(s) carve out the time to chip away at some of this debt. Making your legacy APIs visible is something that has to be addressed in an ongoing way, making cleaning up technical debt something you do alongside your regular work.
