Fun fact: For most companies that create APIs, the number of internal APIs they develop and use greatly exceeds that of external APIs. According to RapidAPI’s 2020-2021 Developer Survey, 75% of developers reported working on internal APIs.
While external APIs get a lot of attention, internal APIs are the workhorses employees use daily to run the company and serve customers, and they are a critical part of the API journey.
There are many similarities between building internal vs. external APIs, and many of the same challenges and hurdles still exist for standing up an API program regardless of what kind of APIs will be produced. There are ample opportunities for things to go wrong. And without some guardrails in place, API programs can quickly spin out of control and suffer from a lack of standardization, limited visibility into the program, duplicated efforts, and reduced usability and user adoption.
On the other hand, a lot can go right when a thoughtful and systematic approach is taken from the beginning before any dev work takes place. Design-first API programs save companies time and money — and produce better APIs that people want to use.
With a design-first approach, you can reduce duplication of effort, improve visibility into your APIs, gain a better understanding of what’s working, and improve standardization and efficiency. With this approach, you can reuse and even automate components and create APIs more quickly when needs are identified.
With these risks and opportunities in mind, here are three of the most important API strategy best practices to follow when building an internal API program:
Design-First Still Applies to Internal APIs
The 2021 State of the API Report by Postman found that the companies they deemed to be design-first leaders “produce APIs more quickly, deploy more frequently, have fewer failures, and recover more swiftly when failures occur.” This study didn’t focus solely on internal APIs, but it is completely applicable.
While there are many benefits to design-first APIs, the most impactful are time and money. A recent case study by wefox, a leading European digital insurer, stated: “Through improved processes and the proper tools like Stoplight, wefox has become 60% faster and has been able to increase their release frequency to daily, even multiple times per day.”
This completely aligns with our experience working with hundreds of companies. Design-first processes are predictable, consistent, and yield higher-quality products.
Increased uptake and adoption are also important to mention. Developers love to reuse quality components that are reliable and predictable, and they will reuse well-crafted APIs over and over again, compounding the return on investment (ROI) for your company with each iteration.
Treat Internal Users Like Customers
If you want your employees to adopt and use an API, treat them as you would treat the potential customers or external users for an external API. They are end-users after all, and as end-users, the ultimate success or failure of the API is in their hands. If they don’t like it, they won’t use it.
The good news is that this is easy to accomplish. Pick a small group of early adopters from across the organization who can serve as champions for the new API, and let them in on the big picture and development roadmap from the outset. Get their feedback early and often on key features, including:
- Design and user experience
- Language and terminology
- Key indicators to track
- How often the group they represent will use the API
- Opportunities for improvement
It’s equally important to listen and be responsive. People need to know they’ve been heard. Make their requested changes when possible, and explain why those that could not be implemented didn’t work out.
It’s all about transparency, communication, and building a sense of ownership among internal stakeholders.
If every member of the API team has equity and a sense of pride in the API, they are more likely to use the API and promote its use within their user group.
Top talent is hard to find and retain, and people costs are the single biggest line item for most tech companies. So it makes sense to keep your people happy. Give them quality APIs that help them excel and are a delight to work with, and your company will realize benefits across the board.
Treat Your Internal API Program as an Opportunity
It’s a surprisingly common scenario: A company develops a great internal API that exposes or repackages a data set to solve an internal problem — and then someone realizes that the same data set would also have value to third parties or customers.
Internal APIs should be approached as opportunities with the potential to be monetized. Rather than treating them as one-off projects that absorb time and money, recognize that each API is an investment with the potential to pay off in more ways than one. Each independent component has inherent value and likely multiple use cases, some of which may end up being profitable.
When viewed through the lens of potential ROI, it’s easier to keep in mind that every internal API deserves the same thought, time, and care that an external API does.
How to Get Started
The first step is to determine who in your organization has the mandate to run your internal API program, and then clearly communicate that information across the organization. It’s important to have the right person watching and guiding the entire system of API engineering and developing a design-first process.
Stoplight excels at helping companies stand up successful API programs, and we offer several open-source tools to streamline and orchestrate your design-first development process.
You can also check out our API Intersection podcast (this episode about developing internal standards for APIs would be a good place to start) or take a look at this recent blog from Stoplight CTO Jason Harmon about how to get started building APIs.
Are you thinking about building an internal API program? If so, what do you see as the biggest challenges that you foresee for the APIs industry?
