Do Not Do That API — It Will Not End Well

One of the best things about writing on API Evangelist is I get to explore territory you don’t when working at an API service provider. There is no venture backed startup that will let me write a blog post telling you not to do APIs. I have contributed my fair share of mindless API cheer leading over the years, and can easily consider myself complicit in a lot of really bad APIs. Which leaves me thinking about why I did that API in the first place and feeling sad for the poor souls who are in charge of sustaining that API today (I am sorry). It all leaves me with a strong feeling that you should probably not do that API in the first place, it really will not end well.

Do not even start building that API. You do not possess the right business awareness for it to be successful. You haven’t even talked to the business folk who will be selling this API, and if you did, you would learn that they really don’t care about the same things you do, and really haven’t done the work to understand what consumers are actually needing. Those requirements you received were hastily written at 4:30 PM on a Friday before they headed to the bar to get multiple rounds of drinks. I know you think you have a handle on the intended business outcomes and feel like you understand what customers need, but you don’t. You are so far away from the action, and you are so privileged and isolated in your day to day work, you aren’t the person to be designing this API. You may know infrastructure and code, but you don’t have the business chops at all, so please just stop here.

Your whole world is set up for velocity and focusing on what is next. Your department dropped every priority to respond to artificial intelligence and you will do the same for whatever blows in next. Your entire incentive model is structured around you closing Jira tickets that were ill conceived in the first place. You do not have time to sit down and properly design this API, let alone seek feedback from other stakeholders. That is just too much work. You are a coder. Planning, design, mocking, documenting, feedback loops all take emails and meetings. Screw that. You just need to get coding. It is what you do. It is where the value lies. Just get out of your way with all of that touchy feely crap. That will take weeks, if not months-—you will get you something coded up this week. You are confident in your world because you do not go outside of it much, which is precisely why the API you develop will fail, because you don’t have the awareness of what business needs, and what consumers will actually use, you are just a Doozer—you Dooze.

Climb to the highest point in your company and look out over all the APIs already in operation. Can you see them? Do all of those APIs do what they were supposed to do? What percentage of the APIs in production or liabilities versus assets? Thank god it isn’t your responsibility to worry about all of that, and it is actually pretty funny that your business leadership, and your product managers can’t actually “see” this sprawl-—otherwise it might terrify them. You are just a cog in a wheel producing more of that. A technical debt Doozer. In this sprint you may feel like you are delivering value, but with the next one you will be required to deliver more features on your API, all without the proper planning and alignment with business, or the consumer. After that you will be denied the opportunity to optimize performance and address any cleanup that is needed so that you can focus on that next API. Take a stand now, do not do that API, it will not end well. Stop this madness right now.

Why do we do APIs if we aren’t going to do them well? Why do we move fast and tell stories that we are in alignment with our consumers when we are not? Why do we listen to the stories of analysts (like me) who perpetually tell us we need to do APIs? Why are there only stories about doing APIs, and not stories about not doing APIs? There is only forward motion in this game. If you aren’t moving forward, someone else well. If you slow down even a little bit to properly plan, you are giving your competitor an edge. It is funny that we don’t see creating all of this mindless technical debt as giving our competitors an edge by slowing ourselves down. It is telling that we are so good at doing APIs and not good at not doing APIs. Even this story is actually about doing APIs well. It is about properly thinking through business outcomes and crafting those business requirements. It is about taking the time to properly design, mock, and document your API, and take the time to get the buy-in of your API stakeholders (do you know who they are?). This story isn’t about not doing APIs, it is about not doing that API if you aren’t going to do it well. I can’t even write a genuine “do not do that API” story-—what is wrong with me?