I like studying APIs. I like to think about how to do APIs well. I enjoy handcrafting a fully fleshed out OpenAPI definition for my APIs. The challenge is convincing other folks of the same. I see the benefits of doing APIs well, and I understand doing the consequences of not doing them well. But, do others? I never assume they do. I assume that most people are just looking to get an immediate job done, and aren’t too concerned with the bigger picture. I think people have the perception that technology moves too fast, and they either do not have the time to consider the consequences, or they know that they will have moved on by the time the consequences are realized. I’m pretty convinced that most of our work on API design, governance, and other approaches to try and standardize how we do things will fall on deaf ears. Not that we shouldn’t keep trying, but I think it helps if we are honest about how this will utlimately play out.
If I give a talk about good API design at a tech conference everyone who shows up for the talk is excited about good API design. If I give a talk about good API design within an enterprise organization and leadership mandates everyone attend, not everyone present is excited, let alone cares about API design. I wish people would care about API design, and be open to learning about how others are designing their APIs, but they aren’t. Mostly it is because developers aren’t given the space within their regular sprints to care, but it is also because people are only looking to satisfy the JIRA ticket they are given, and often times the ticket has said nothing about the API being well designed, and consistent with other teams. Even with teams that have been given sufficient API design training and governance, if it isn’t explicitly called out as part of the acceptance criteria for a specific unit of work, it is unlikely to get done.
I guess this is where automation and pipeline testing comes into play right? We make sure there is a healthy amount of contract, as well as governance testing across our pipelines. We make sure the design and implementation of each individual API path meet any assertions laid down as part of the design and governance efforts. I think this will definitely make a significant impact on things, and go further than just depending on individuals to step up, but I still think there will be plenty of pushback on API governance by some teams and individuals, and there will always be projects that manage to escape governance efforts. With this in mind we are going to have to be more honest that there will always be chaos. We will never have a handle on all of our schema, and be able to consistently deliver APIs across teams at scale. Again, it doesn’t mean we shouldn’t try. It means that we should also be investing in tools, services, and processes that help us make sense of the chaos, and find ways to work in this environment. Knowing that it will always be like this with things getting better or worse from time to time, depending on team and leadership turnover across the enterprise.
After a decade of watching all of this play out I am just not convinced that everyone is really interested in getting their house in order. The number of APIs is exponentially growing, with meaningful investment in governance by enterprise organizations, and service or tooling makers progressing at a very slow pace. There is no way that we will be able to keep up. This story is triggered by me analyzing thousands of Swagger, OpenAPI, and Postman collections I have harvested across GitHub. I see a lot of public APIs, but I also see people trying to document, mock, test, and make sense of internal APIs. These are rarely Swagger, OpenAPI, and Postman collections from people working to define, design, and deliver APIs—it is mostly people trying to just make sense of the world around them, and deliver what they need to be successful in the moment. These API artifacts aren’t complete, they are simply done enough to allow someone to publish documentation, generate a mock, generate tests, scan for security holes, or the numerous other things they need to move from A to B. These artifacts tell me that people are just trying to stay afloat, make sense of what is going on around them, and rarely have time and bandwidth to do things well. Reflecting chaos as usual I encounter across every enterprise organization I have worked with over the years.
