Your API and Schema Is That Complex Because You Have Not Done The Hard Work To Simplify

I find myself looking at a number of my more complex API designs, and saying to myself, “this isn’t complicated because it is hard, it is complicated because I did not spend the time required to simplify it appropriately”. There are many factors contributing to this reality, but I find that more often than not it is because I’m over-engineering something, and I am caught up in the moment focusing on a purely computation approach, and not considering the wider human, business, and other less binary aspects of delivering APIs.

While I am definitely my own worst enemy in many API deliver scenarios, I’d say there are a wide range of factors that are influencing how well, or poorly that I design my API resources, with just a handful of them being:

  • Domain - I just do not have the domain knowledge required to get the job done properly.
  • Consumer - I just do not have the knowledge I need of my end consumers to do things right.
  • Bandwidth - I just do not have the breathing room to properly sit down and make it happen.
  • Narcissism - I am the best at this, I know what is needed, and I deem this complexity necessary.
  • Lazy - I am just too damn lazy to actually dig in and get this done properly in the first place.
  • Caring - I just do not give a shit enough to actually go the extra distance with API design.
  • Dumb - This API is dumb, and I really should not be developing it in the first place.

These are just a few of the reasons why I settle for complexity over simplicity in my API designs. It isn’t right. However, it seems to be a repeating pattern in some of my work. It is something that I should be exploring more. For me to understand why my work isn’t always of highest quality possible I need to explore each of these areas and understand where I can make improvements, and which areas I cannot. Of course I want to improve in my work, and reach new heights with my career, but I can’t help be dogged by imperfections that seem out of my control…or are they?

I have witnessed API simplicity. APIs that do powerful and seemingly complicated things, but in an easy and distilled manner. I know that it is possible to do, but I can’t help but feel that 90% of my API designs fall short of this reality. Some get very close, while others look like amateur hour. One thing is clear. If I’m going to deliver high quality simple and intuitive APIs, I’m going to have to work very hard at it. No matter how much experience I have, I can only improve the process so much, and there will always be a significant amount of investment required to take things to the next level.