1. API First Concepts
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):
Validate the impact in the core business
Qualify the key criteria (technology partner, success and even failure)
Define a short and agile sprint/delivery based on an MVP and MVA
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:
Are we about to use PHP, Python, Django?
Are we fine to use HTML5 with bootstrap or material?
Can we check some themes in Themeforest?
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:
Question: Tell us what you sell the most? And how?
Business: We do have a great contract with some hotel brands and at some destinations and during some seasons our prices are by far the best! As a result, many agencies can book offers at our desktop system and we take care of the logistics.
Note: If you wish to learn more about the technical aspects, such as API verbs, nouns, etc, please refer to relevant material in the WSO2 Library.
Question: Describe the most important information you need at the point of booking a hotel room.
Business: The key things we need to know about the reservation are destination, period, type of room and if double bed/twin beds, and how the payment will be made. Sometimes when we allow direct payments, we may face some issues with recovering our commission, which isn’t very favorable for us.
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.
3.1 Validating impacts in core business
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
Capacity to expand the way to communicate and connect with new business channels and generate new potential revenue streams.
Monetizing these new revenue streams (why not)
Delivery of new applications faster and with more agility given that most of the hard work will be encapsulated by APIs
Service reusability and governance, helping find what assets exist and sharing them more broadly across the organization, including integrations, microservices, legacy databases, stored procedures, etc.
For the organization, it will represent starting jobs with proper tools, and not having to create the tools over and over again from scratch.
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
API First Hackathons: Just drafting potential APIs
Consuming APIs Hackathons: Just checking how the existing applications or partners can consuming your "drafted" APIs
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!"
3.2 Defining your criteria for selecting some solution/partner
It’s important you define some criteria when you have many solutions and partners available out there. For instance, Hostelera used the following criteria:
Some solution where it’s possible to design the APIs as drafting/mocking before any implementation (API: First in the veins)
A cloud-based solution to get the initial project delivered quickly, but according to the traditional IT “owner” of Hostelera, eventually to be hosted in their datacenter in the future, and using the same solution from cloud on premises.
Expand a third-party ecosystem to reach new consumers by defining a very cool marketplace (an API Store), with many social resources, an API rating, and user comments, and be able to generate a pleasant developer community, integrating Hostelera booking functionalities directly into their mobile and other applications.
A solid gateway that’s able to connect API callers to the backend legacy systems in Hostelera, which still uses a very old database based on Informix, and have a bunch of libraries written in C and C++ for a set of features and calculations. Modernizing this system can now be considered, as long as the new system can be accessed using the new APIs; putting the new system in place will be transparent to the API users).
Able to the get their team up and running with a minimal solution in a few days or if possible in a few hours. This agility is important to test ideas and quickly refine them to achieve maximum business impact.
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
3.3.1 What are MVP and MVA?
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:
You had solved the initial issues and/or opportunities to execute your first APIs; now you can prove that your initiative can attract investments and get boosted.
You shall be happy because you launched something that you will not regret, and you will be helping your organization with a new way to look at how things can be easily consumable and programmable; you now have the way to connect the dots and make the business connect even remote dots more easily.
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.
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
Could I reuse my stored procedures, packages as services exposed via REST/SOAP? How hard and productive will it be?
Can I still use my existing messaging queues transactions connected to my new services and APIs?
That file integrations that results in inserts in some of those tables in the database are ready and good enough to be exposed via my new services and consequently as my new APIs?
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.
4. Look: Evaluate: Repeat
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
How are you planning your integration architecture? Microservices or lightweight integrations platforms?
How will your continuous delivery work? How will it be aligned with your devops?
How are you thinking about securing your organization in that digital world?
How are you treating your analytics? Does real-time analytics impact your business?
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.