APIs? What are they? That is the million dollar question nowadays. We could come up with thousands of answers, but we prefer this simple analogy.
A very easy analogy might be: Your APIs are to your business what a panel and controls are to a car. Most people have no clue about how a car works under the hood, but know that if you push the accelerator, the car goes faster, and if you apply your brakes, the car will eventually stop (Figure 1). Similarly, things like climate control, blind spot detection, and adaptive cruise control provide a safer and more enjoyable driving experience without you having to worry about how those systems do what they do. Well, that is exactly how good APIs should work!
In a very objective way: APIs allow you to develop higher quality solutions more securely, quickly, and easily, and will allow your solutions to be created faster and with higher quality, since your developers don't have to understand details of the business function in a wider and deeper way. For that reason, the market is increasingly creating applications composed of internal and external APIs, pretty much like Uber did (using Google Maps, PayPal, Social Logins, etc.). The outcome will be better applications and more competition among API providers.
API strategy or the API economy encompasses several aspects; these include adopting the right strategy to expose such internal capabilities in the organizations in a highly reusable fashion, ensuring they’re easy to consume internally and externally, and possibly being able to generate business and revenue.
Here’s another good way to look at this - in the 1990s, not having a website for a company was not good, but, today, a company with no plans of having at least one API might be unusual.
So what should companies be looking for in order to have a successful API strategy?
We understand that an API initiative must include the following phases (Figure 2):
This document intends to explain in a very vendor-agnostic way how it’s possible to achieve these points in an effective way, and also safely, protecting not only your time, but your team and investments. In the end, we would like to provide a set of guidelines to build credibility and trust with your company to execute a great API strategy and enable significant adoption.
As we have moved towards mobile-first development in the past, it is very common now that we face the API-first approach, which consists of representing your business functions as APIs. Therefore, let's use a hypothetical travel business case example, a kind that many of us are familiar with how it works, as traveling, booking a flight or hotel, are common activities for most people. Let’s assume the name of this business is Hostelera (any similarity to an actual entity is purely coincidental).
Hostelera is a spinoff of a large and traditional tourism group that will share some resources with that new spinoff, while maintaining their own development and business teams. The team supports a desktop application that runs in many travel agencies across the country. Hostelera realizes that they need to execute a digital transformation strategy, and for that reason, they decide to not only operate in B2B transactions (where companies do business with other companies) but to play into the B2C space (where companies can approach the end consumer in the chain). The Hostelera team decided to start by developing the website to attract customers. They started with the following questions:
Well, all those questions above are valuable, but they are far away from impacting the business in a very effective manner. Now we will discover what we can do slightly differently.
In order to support Hostelera in their digital transformation initiative, we were invited to help them, but initially just talking about business and nothing else. Now, let’s take a look at our initial questions:
After we evaluate what was important for Hostelera, the tech people had uncovered what capabilities exist in the organization (as is), and after brainstorming with the business and technology teams, we came up with the following APIs to get started (Figure 3).
With the information provided, we can now design the APIs in a very easy manner using an industry standard called Swagger.
Some API management solutions have the Swagger Editor built in to their solution, and with this you can define your entire API "contract" and plug in the final implementation later. As a result, you can combine both technology and business to define what’s really important to be delivered as the initial APIs. The goal here is to be already connecting with our MVP and MVA that will be proposed later on in this paper.
Figure 4 is an example of the Swagger Editor where you can see the result of the meeting and efforts applied by both the business as well as technology.
Given that the APIs are ready for initial usage, what about the website?
Simple answer: With the APIs ready, to build a site, web app, mobile app, bots, integrating with partners, etc., connecting to your API (and thus with your core business) is extremely easy.
The following section describes some important phases when creating your APIs.
If you don't know the exact benefits an API strategy can bring to your organization, and if you consider this a tough task at least in the short term, it may help to do some interactions/sprints following the principles of API: First.
The direct impacts of an API strategy into an organization include
However, there is a tricky part in all of this. You have to make sure that you have the proper organization engagement with your API initiative. The sad truth is that if your company doesn't embrace exposing and reusing APIs as a key component of transforming and impacting the business, based on some of our experiences, there is a higher risk of failure. For this reason, sometimes interns to C-levels must know that you are investing time, money, and company efforts to accomplish something that will have a valuable outcome and it also directly helps to improve the business. For this reason, it’s important you involve as many people as possible in your API initiative. Some ways to do that might be
These types of initiatives can bring you real KPIs that can make your company "buy in" to your initiative (idea). That is one of the most fundamental things in very successful API initiatives.
Let’s consider the Hostelera example again; they were losing market share and revenue and they noticed that a direct B2C interaction could capture more market share, increase commissions, generate new sales channels, or further expand opportunities. After all, they have significant experience in the market. After evaluating all the risks and investments, the company founder and CEO, a "baby boomer"1, starts spreading the word that the company was “investing in that thing called APIs. And that API will save our ship!"
It’s important you define some criteria when you have many solutions and partners available out there. For instance, Hostelera used the following criteria:
Defining the right path forward is very important. For this reason, with the organization's support, try to evaluate what’s really important to your business and try looking for a platform that is able to accomplish your goals within your budgets and expectations. Moreover, it’s important to measure the quality and good reference cases as well. Define your criteria and go to market.
It’s crucial to involve your technology partner in your adoption process. Usually we recommend an agile approach, based on quick sprints, where the most important goal is to have something ready in a short time. The ideal timeframe would be 1 month (no more than this, but might be even less); once you extend that deadline you can miss your focus and overwhelm your team. It’s important to achieve a quick win or to discover what’s preventing a win quickly so you can adjust your plans and try again. That is the most important point at this moment: to reach a quick win!
The organization might be waiting for fast results, but think that everything must be incremental and iterative in order to have a pragmatic and objective adoption.
As a proposal for timelines, we suggest the following:
1. Training and workshops for your solution
2. Reach and MVPs and MVA definition
3. Plan your API marketplace (internal, external, etc.)
Get from 2 to 3 APIs to start your MVP:
1. Get those 2, 3 APIs for implementing them
2. Those APIs must be 100% aligned with your business
3. Define key points from your architecture: security, deployment, integration models, etc.
1. Continue implementation
2. Check which satellite technologies you might apply, microservices, integrations, etc.
3. Close the MVP and MVA
1. Marketplace theme customization
2. Publish the APIs
3. Promote a kind of internal engagement event for launching the MVP
A minimum viable product, or MVP (or minimum delivery possible in a certain time period), is the minimum of minimum for your product/idea works. Note that an MVP launch might be totally incremental and versionable, where you can evolve with every new interaction. The main idea of your MVP is that in a single month (or less) you could have something like https://api.mycompany.com, bootstrapping your API initiative, making it real, and anything else that event might mean for your organization:
Again, your MVP/initiative shall be incremental and continuous, always adding new capabilities and reusing what you already did as illustrated in Figure 5 below.
Figure 5: How a MVP must evolve - https://blog.engineyard.com/2015/actually-mvp
A minimum viable architecture, or MVA, is the minimum architecture that you will use to build your services that will be exposed as APIs. There are companies that are able to reuse their legacy integrations, actual integrations, database schemas, or even the database's components, such as Stored Procedures; it can also include those that contain a bunch of business logic inside. Note that your MVA is also incremental and continuous, and eventually you might change that database vendor dependency and replace those stored procedures for cool and fancy microservices deployed in a very fashion orchestrated docker cluster. However, other companies will start from scratch and rewrite some of their new services using Java, Go, .Net, Python, Elixir, etc. but this is not relevant to your API layer. Hence, such important decisions might be taken during this period. They key is to keep the architecture resilient enough in order to accommodate any scenario you might face from now on.
Some common questions during that period might be
The answers for that and a long list of potential other questions will be in the result of the alignment of your MVA with your MVP. In other words, what can you do to accelerate your MVP? Once the MVP is ready, never forget the basics regarding agile methods. You can evaluate your architecture and promote/expose services in the most convenient way for you at any moment. However, keep in mind that you have to align the expectations, timing, the MVP, and the MVA as everything is sort of connected.
Some organizations, for instance, already have their enterprise service bus (ESBs), which might be already exposing many services. There is no issue getting started with this as you don’t have to ‘change the team that’s winning the game.’ We too have seen many customers using different flavors of ESBs, like exposing SOAP services and for powerful API managers/gateways the task of converting SOAP to REST is something incredibly easy. Although ESBs are still prevalent, some organizations simply don't like such technology for many different reasons, and they prefer microservices, micro-integrations, or related approaches. It’s alright to follow the same model unless the API gateway in your API manager suite is not capable of supporting such challenges and you’re faced with a very agile environment for architecture decisions.
It's crucial to check at the end of each phase what worked and what didn’t and adjust the airplane's wings while it’s in flight, in keeping with the realities of today’s connected world. There is no magic recipe or any phenomenal book that might be able to help organizations transform and reach the digital era. To transform, it’s necessary to gain as much insight, information, and indicators as you can and evaluate them. Then, based on facts, and definitely with a pinch of creativity and courage, make things happen.
This paper was not intended to be a blockbuster, but to give you a sharp orientation on how to conduct an API strategy adoption. It demonstrates the most pragmatic way with insights and real-life experiences from some of our field consultants. At the end of the day, most theories get tossed when an initiative does not succeed. Therefore, we described some primordial phases in adopting APIs. There are a bunch of other topics that were not covered in this paper, such as
Many of those points, will vary according your existing or chosen technological partners, while some of those will allow you to use what you have at home; others can bring you new practices that will let you start from scratch, what can be good or not, but in the end, it will drive us to one of the points in that whitepaper: "What is important for you and your company?" Can you recall the criteria topic that we mentioned before? That is the mental trigger that we would like to take with you.
For more details about our solutions or to discuss a specific requirement