APIs are not just about code

Author(s): Oryan Omer

Originally published on Towards AI.

Software Engineering

So you want to be API-first?

Deciding to become an API-first product is not a trivial decision to be made by a company. There needs to be a deep alignment throughout the company, from R&D all the way to marketing, on why and how an API-first approach will accelerate development, go-to-market, and the business at large. But more importantly, just like you need product-market fit, you need product-market-API fit. There is a big difference between externalizing APIs and being API-first, and depending on your clients and their use cases, you’ll need to understand whether API or API-first is the right choice for you.

This post explores how APIs and API-first impact both the business and R&D through the evolution we at Superwise went through as we became an API-first product and business.

Luckily we don’t need to go into depth here. APIs are so common at this point that even the most non-technical of business persona knows that an API is an Application Programming Interface that standardizes communications so any two apps can send/receive data between each other. The problem with this is that they are so ubiquitous today that occasionally you’ll see businesses pushing for APIs without a strong product-API fit and/ or product-dev maturity.

Should your APIs be first-class citizens?

You need to ask yourself a set of criteria before deciding what to do regarding APIs; go all-in and become API-first, expose a set of APIs, or say no to APIs in their entirety. There is no magic number of yeses or nos here; you might even say yes to everything listed below, and still, API-first will be wrong for your product/business.

Bigger picture fit

The first thing you need to figure out is where your API fits in the bigger picture and how integral it is to enhancing value.

• Is your solution part of a more extensive process? Yes, users tend to get annoyed with the overabundance of tools and platforms they need to use to do their jobs, but there is a big difference between a tool used monthly and a daily tool.
• Does consuming your solution via API generate more value for users? BI is an excellent example of higher value via API by making information accessible to all stakeholders in the organization.

Look at model observability for example. It isn’t necessarily a day-to-day tool, but it is mission-critical, and when something goes wrong with ML in production, monitoring can trigger any set of processes to resolve the anomalies. Furthermore, almost always, you’ll also need to expose issues to other stakeholders in the organization so they can take preventive actions until the root cause is uncovered and the incident is resolved.

Consistent reusability

So you have a big picture fit, and your API creates additional value to your users; fantastic. Now think about how your users use your product and if this translates consistently, across your user base, to API usage.

• Is your product-market fit ubiquitous? Will most of your users want to use the API more or less in the same way? Social login is an excellent example of API-first. It’s a product with consistent reusability across the user base.
• Can any organization implement your API? This is about both endpoints, not just your API. If the system you typically integrate into is niche or requires specific domain knowledge, it could be that not all organizations will be receptive to your API because they don’t have the necessary resources to bake it into their processes.
• Do your users need an API or all the APIs? Is it worth your time and effort to go API-first, or will you get the same impact with one or two APIs in a non-API-first approach?

Superwise’s journey to API-first

In all honesty, when we first started exposing APIs, we didn’t have a robust process in place, much less an API-first mentality. We were exposing quite a few APIs, some for internal use in our web application and some for direct customer consumption. It was a headache to maintain both the APIs and their documentation, and we had no flow in place to handle the influx of customer requests to change /create APIs. In addition, and probably most importantly, because we didn’t have a well-defined process and mindset in place, there was a ton of miscommunication and ‘lost in translation moments between our backend and frontend teams that resulted, more often than I want to admit, in bugs and over-fetching.

All of these problems stemming from our APIs made us sit down and think about what is right for us when it comes to APIs and how to build processes that facilitate scale, both ours and our customers, without the issues we experienced till now. The result is evident from this post’s title; we decided to go API-first.

So what did we do?

APIs are a big deal for our customers, internal and external, and our product depends on the quality of our APIs and their ability to deliver value seamlessly.

• Who is the client? Internal? External?
• Are the API requests and responses aligned and fit the client’s use case? You need to find a balance between minimizing API calls and invocation explicitly. Too many API calls are inefficient, but confusing invocations are ineffective — both are detrimental to user experience.

Once we figured all this out, we documented our APIs to create a “construct” of how the APIs will be consumed. This gives our frontend team the ability to mock data and continue developing frontend features without waiting on support from the backend. This way of thinking about our APIs as an integral part of the product makes us always examine any request to ensure that our APIs stay reusable and flexible.

The advantages of going API-first

Going API-first, both technically and in terms of mindset, had a powerful impact on our ability to scale the application and integrate with external services rapidly. Before we started thinking about our APIs as first-class citizens when we had a load on a specific API, it was impossible to scale just that specific API; we had to scale all our applications. With the switch to API-first, all our APIs are designed for a microservice with a specific task. This enables us to scale each API according to its load and be efficient with our resources.

• Minimize dependencies — An API-first mindset brings dependencies to the forefront and encourages us to decouple APIs by design so that updates/changes can be done on the API level and not at the application level, which affects all APIs. This is not always attainable, but where it is, upgrading/changing APIs will be a more effortless and independent task.
• Parallelize development — Development teams can work in parallel by creating contracts (i,e: documenting your APIs route, requests, responses) between services on how the data will be exposed. This way, developers do not have to wait for updates to an API to be released before moving on to the next API, and teams can mock APIs and test API dependencies based on the established API definition.
• Speed up the development cycle — API-first means we design our APIs before coding. Early feedback on the design allows the team to adapt to new inputs while the cost of change is still relatively low, reducing overall cost over the project’s lifetime.
• QA in design — double down on the design phase because fixing issues once APIs are coded costs a lot more than fixing them during the design phase.
• Design for reusability — You can also reduce development costs by reusing components across multiple API projects.

Key points to become API-first

Implementing an API-first development approach in your organization requires planning, cooperation, and enforcement. Here are some key points and concepts to bake into your API-first strategy to make sure it’s a success:

• Get early feedback — Understanding who your API clients are, inside and outside of your organization, and getting early feedback on API designs helps you ensure API-use case fit. This will make APIs easier to use and shorten your development cycle.
• Always design first — API (design)-first means you describe every API design in an iterative way that both humans and computers can understand — before you write any code. API consumption is part of the design process, and it’s important to remember that clients (in plural) will interact with the feature through an API, so you need to always keep everyone in mind and not focus too much on a specific client. Considering design first will also make it easier to understand all the dependencies in the task.
• Document your APIs — API documentation is a must as it creates a construct between clients and developers. The documentation is critical to ensure that the API consumption is effective and efficient. We want to be exact in the language and examples, so the client gets maximum impact with minimum effort.
• Automate your processes — Use tools like SwaggerHub to automate processes like generating API documentation, style validation, API mocking, and versioning.
• Make it easy to get started — Provide interactive documentation and sandboxes so that developers can try out API endpoints and get started building apps with your APIs right away.

‍

A lot has been said about going API-first, and there are many resources and best practices (for example, these articles from Auth0 and Swagger) that can help you through the transition. But going API-first doesn’t necessarily require refactoring your existing applications; it’s about embracing a different mindset. For us, it was without a doubt the right path to take, we see it in customer satisfaction and increased usage, and we see it in how we are scaling faster and more efficiently, and we see it in how we are developing and deploying new capabilities faster to our customers.

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI