It is tough to help developers think outside of the world they operate within. Most software is still developed and managed within silos, knowing it’s inner workings will never be seen by anyone outside of the team. This mode of operation is a rich environment for poor code quality, and teams with port communication. This is one of the reasons I’ve embraced web APIs, after running software development teams since the 1990s, I’ve been put in charge of some pretty dysfunctional teams, and some pretty unwieldy legacy codebases, so once I started working out in the open using web APIs, I did’t want to go back. Web APIs aren’t the cure for all of our technology problems, but it does begin to let some sunlight in on some messed up ways of doing things.
One common illness I still see trickling out of API operations are developers not using plain language. Speaking in acronyms, code, and other cryptic ways of articulating the resources they are exposing. I came across a set of API resources for managing a DEG the other day. You could add, updated, delete and get DEGs. You can also pull analytics, history, and other elements of a DEG. I spent about 10-15 minutes looking around their developer portal, documentation, and even Googling, but never could figure out what a DEG was. Nowhere in their documentation did they ever tell consumers what a DEG was, you just had to be in the know I guess. The API designer (if that occurred) and developer had never stopped to consider that maybe someone would stumble across their very public API and not know what a DEG was. Demonstrating how us developers have trouble thinking outside our silos, and thinking about what others will need.
There is no reason that your API paths shouldn’t be plain language, using common words. I’m not even talking about good RESTful resource design, I’m simply talking about looking at the URI for an API and being able to understand what it is because it used words we can understand. If you have trouble pausing, and stepping back, and thinking what some random 3rd party developer will interpret your API paths as, I recommend printing them out and sharing them with someone that isn’t on your team, and familiar with the resources you work with. Even if your APIs aren’t going to be public, someday you will be gone, and maybe your documentation isn’t up to date, and someone will have to reverse engineer what your API does. There is no reason your API should hide what it does, and not speak for itself, providing an intuitive, plain language description fo the value it possesses.
I look at hundreds of APIs each month. I push myself to understand what an API does in seconds, or minutes. When I spend 10-15 minutes unsuccessfully to understand what an API does, there is a problem with its design. I’m not talking about good API design, I’m just talking about coherent API design. There is no reason you should have an acronym in your API path. I don’t care how short-lived, or internal you view this API. These are often times the APIs that end up sticking around for generations, and becoming part of the technical debt future teams will have to tackle. Don’t be part of the problem in the future. Speak in plain language, and make your API paths speak for themselves. Make them speak to as wide as possible audience as you can. Make them reach outside of your developer circles, and become something any human can copy and paste, and put to work as part of their daily routine.
