Helping Business Users Get Over Perceived Technical Gaps When It Comes To API Design

Every single API project I’m working on currently has one or more business users involved, or specifically leading the work. With every business user, no matter how fearless they are, there is always a pretty heavy perception that some things are over their head. I see this over and over when it comes to API design, and the usage of OpenAPI to define an API. I’ve known a handful of folks who aren’t programmers, and have learned OpenAPI fluently, but for the most part, all business users tend to put up a barrier when it comes to learning OpenAPI–it lives in the realm of code, and exists beyond what they are capable of.

I get that folks are turned off by being exposed to code. Learning to read code takes a significant amount of time, and with the more framework, libraries, and other layers, you can find yourself pretty lost, pretty quickly. However, with OpenAPI, everything I do tends to be YAML, making it much more readable to humans. While there are rules and structure to things, I don’t feel it is out of the realm of the average user to study, learn, and eventually bring into focus. Along with the OpenAPI rules, there are a good deal of HTTP literacy required to fully understand what is going on, but I feel like the API design process is a much more forgiving environment to learn these things for both developers and business users.

I put the ownership of everything technical being complicated squarely on the shoulders of IT and developer folks. We’ve gone out of our way to make this stuff difficult to access, and out of reach of the average person. We’ve spent decades keeping people we didn’t see fit from having a seat at the table. However, increasingly I also feel like there is a significant amount of ownership to be given to business users who are willing to put up walls when there really is not reason. I think the API design layer is one place aspect of doing business with APIs where the average business user throws up unnecessary bluster around technical complexity, where it doesn’t actually exist. The definition of an API is simply a contract, no more complicated than a robust word document or spreadsheet, completely within the realm of understanding for any engaged user.

There is a pretty big opportunity to narrow the gap that exists between technical and business users with APIs. The challenge will be that many technologists want to keep things closed off to business users so they can charge for, and generate revenue when it comes to bridging the gap. We also have to figure out how to help business users better understand where the technical line is, and the importance that they become OpenAPI fluent, and have a stake in the API design conversation. Once I get back to my API training work, I’m going to think about a version of my API design curriculum, specifically for non-developer users. My goal is to figure out what it takes to onboard more business users to the world of APIs design, and make sure we balance out who is at the table when we are defining API solutions.