What Is API First?

I really struggled with this piece on API-first. It is one of those holistic API advice pieces I am very conflicted about. API-first feels like yet another marketing phrase or latest trend like microservices. So as I am writing down my thoughts over the last couple weeks on this, my bullshit-o-meter kept going off. Honestly it still is, but I still feel like there is enough value here that I can move forward with a story. As my co-worker Joyce rightfully pointed out in a meeting recently, API-first is one of those phrases we regularly throw out there without much assessment, agreement, or real definition of what it means. That is one reason it feels so wrong at times, because I feel like it is one of those feel good things we throw out there, but never really think too deeply about while doing, or after it fails and we’ve moved on to the next thing.

With all of that said, I still believe that API-first can matter, if we, as Joyce points out, actually define what we mean by it. I think there is a lot of misconception about what we mean by API-firsat, and I’d like to stimulate conversation around what it means, if not just get more precise around how I talk about it. One concern I have about the API-first discussion is that once again it is something that only concerns developers when delivering APIs, and that it is something that business folks shouldn’t worry their pretty little heads about. This is a classic historical technique for dividing and conquering the technology-human paradigm that is spreading across society, and is something I am not interested in perpetuating. So I have broken down API-first discussion into two main parts, one through the technical lens, and another through how business folks will need to be made aware of as they continue to employ technology as part of their everyday work.

Looking Through the Technical Lens of an Organization

What does API-first mean to technically mind folks, including architects, developers, and other roles? When leadership, all the way down to the individual developer on teams, begin any new project, why should API-first be the first thing on the table. Not that everything is an API, or gets solved by an API, but we should be thinking about the following.

  • Before developing a web application, develop an API first.
  • Before developing a mobile application, develop an API first.
  • Before developing a device application, develop an API first.
  • Before attempting any system integration, develop an API first.
  • Before directly connecting to a databases, develop an API first.

I am not saying that APIs are always the solution. I am just saying they are too often presented as a solution to everyone involved very late in the game. Before you consider doing anything with the web, or any of the other applications the web enables, you should be bringing up API-first. It is less about the API, and more about widening the conversation around how we use technology, and being more thoughtful, organized, and strategic about how we deliver technology. It really isn’t just about APIs.

Why API-First for Technical Folks?

Naturally folks are going to ask me why? Why should we be brining up API-first before we get to work developing any single application. It isn’t that APIs are always the right or superior choice, it is that the API-first discussion brings up many things that need consideration, and help us break down who should have a seat at the table. Providing me with a handful of definitions I’m going to go to when it comes to answer why API-first as part of discussions with technical folks.

  • Allow potential stakeholders to communicate about what is needed before applications are actually build.
  • API will reduce redundancy across multiple types of applications and integrations.
  • API will allow for reuse across multiple types of applications and integrations.
  • API will allow for increased efficiency across multiple types of applications and integrations.
  • API will allow for centralization of observability across applications and integrations.
  • API will allow for meeting needs of the known knowns, known unknowns, and help address unknown unknowns.

Again, it isn’t really about APIs. API-first is more of a vehicle for making sure we zoom out and consider the bigger picture. Which is one of the main reasons why it is so important that this isn’t just a technical discussion held amongst the usual set of wizards that have guided application and infrastructure development of the past. For API to really work this can’t just be about architects and developers, it has to be inclusive to the business people who are usually pulling the strings and making the business decisions that decide whether or not an application lives or dies in the first place.

Looking Through the Business Lens of an Organization

I am adamant that API-first isn’t something that should just roll of the lips of technically inclined folks. If business users aren’t equipped to understand why APIs matter, and that they should have a role in their development, then we should just give up on this whole API thing. I am not saying that business users should understand the nuts and bolts of everything that is occurring throughout the API life cycle, but we shouldn’t be hiding things from them, and we should be working hard to regularly educate and equipping them with the ability to ask…

  • Before any service or software solution is used or purchased, ask if it has an API first.
  • Before developing a web application, develop an API first.
  • Before developing a mobile application, develop an API first.
  • Before developing a device application, develop an API first.
  • Before you open ticket with service provider that the UI can’t do something, look for an API first.
  • Before custom programming a migration between systems, look for an API first.
  • Before manually attempting a bulk process, look for an API first.

If someone at a company, organization, institution, or government agency is going to be in a leadership position involving the development, delivery, operation, sustainment, and support around any desktop, web, mobile, device, or network application, then they should be equipped to ask these questions. They should not be require to understand all the technical details of what is happening, but they should have a seat at the table, be able to ask questions, and be equipped always ask if an effort has considered being API-first.

Why API-First for Business Folks?

As with discussion amongst a more technical crowd, it is natural for folks to ask why. APIs are not the solution to every problem, and there are pros and cons to doing APIs, so asking why is essential. There are numerous reasons why business folks should be asking about API-first when starting a new project, or looking to evolve upon an existing application. I’ll keep iterating upon these reasons, but here are a few of the reasons why business should be learning about API-first and injecting it into conversations with other business and technical groups.

  • All the same reasons as for technical folks, but a few more to things to consider.
  • APIs in some cases will allow you to bypass the need for more technical stakeholders.
  • There are low code / no code options for business users to put APIs to work.
  • User interfaces are meant for narrow audience and APIs cater to as wide as possible audience.
  • The more eyeballs on the pipes behind the applications we depend on the better.
  • Help demystify API technology, and force technical stakeholders to simply and make more accessible.

As you can see, this really isn’t about API. It is about people, communication, and planning. APIs are just a convenient vehicle for introducing healthier approaches to these areas, and better define the human-machine relationship that exists throughout our personal and professional lives. APIs aren’t purely technical. They also have the human meaning and behavioral outcomes coded into their endpoints. APIs are both human and machine readable when they are designed well. This reflects the API-first mandate. APIs aren’t new. Really, the most recent innovation in the development and delivery of APIs that has made a significant impact in how business gets done using APIs, is that they have become simpler, and more accessible to non-developers. Invoking more conversations around the business value of doing APIs, which honestly is the primary driver of why we are not just doing APIs, but also the desktop, web, mobile, device, and network applications that use them.

API-first is important. Not because of some un-defined, superficial way at thinking about technology. API-first is important because it causes us to pause for a moment and think about the bigger picture. Who should be involved. What types of applications are going to need access to this data, content, and algorithms in the near or longer term future. API-first forces us technologists to tap the breaks before diving in, which is one of the reasons us developers are resisting API-first so much. We just want to dive in and get coding, without much thought to the long term consequences, or the unintended side effects. Someone else will have to deal with those consequences. API-first won’t solve all of the challenges we face in the technology sector, and the business sectors who find themselves delivering more technology, but they can help us be more thoughtful and inclusive in how we deliver technology, while also allowing us to move faster, be more agile, nimble, and flexible when it comes to operating in a digital world.