Organizations that adopt an API-first strategy and standardise around the OpenAPI specification are more able to respond to challenges faster than traditional organizations. In this article we look at what API-first means, what the OpenAPI specification is, and then get into three reasons why embracing an API-first strategy will yield rewards for organizations today. We also share how the AppBus Platform is able to quickly modernize existing applications that are ill-equipped to fit into such a API-first strategy.
What do we mean by API-first?
APIs are not new. Application Programming Interfaces have been around ever since two applications needed to exchange information. APIs have evolved from very simple file system data transfers through to complex network based protocols spanning all seven layers of the OSI network stack. What is new is that many organizations have realized that modern APIs offer a way of representing business value in a way that can be quickly consumed by other applications. This in turn has led to the term “programmable enterprise” where the intrinsic value of a business is surfaced through APIs first and foremost, which are subsequently consumed into web and mobile applications that enable employees, partners, and customers to deliver services more efficiently, regardless of the back end technologies. An organization that adopts an API-first strategy typically takes the following approaches to solve business challenges (both new and existing):
- They look at the functions and data needed to solve the business challenge and then set about designing an API to represent those functions and the data. For example: in lifesciences the challenge of adding a new study can be simply represented as a POST function on an API entity called Study with the core data elements specified in the request body.
- The API design is then mapped onto existing applications that must fulfill the request. This is where API management platforms add value by orchestrating requests to existing API services to fulfill the outcome without exposing that complexity to the requestor. In the new study example this might mean creating records on multiple back end applications by calling their individual application APIs.
- Presentation of the API to human users or using it to integrate between applications can start as soon as the design is drafted using mock endpoints. This accelerates the time to value and encourages innovation. In the new study example this might mean selecting a menu in a simple web form to create a new study and capturing the seed data from the form itself.
- Once the API has been designed and delivered it is not constrained to the original business challenge but can be reused in the future to solve other unforeseen challenges. The value effect is multiplied and lock-in is avoided. The API stands on its own and affords a level of abstraction away from the underlying implementation, providing great control and flexibility. Each API endpoint represents a microservice of the business. In the study example, the implementation may touch several application services, however any one of them could be replaced without impacting the API consumers since the API remains the same.
Three reasons to adopt API-first
An API-first strategy brings many rewards but here are three important reasons to adopt this strategy within your organization:
Taking an API-first approach means that innovation through try-fail-succeed can be embraced in a safe environment. New ways of using the core business functions and data that may have accrued over decades can be rapidly combined together, prototyped and evaluated with business leaders in new ways. Since modern APIs are highly consumable, the time taken to build and try new ideas is much lower than traditional methods. An idea can be prototyped and trialed in weeks rather than months and therefore refined much more rapidly. Failing is inexpensive, carries no risk, and can be encouraged, iterating towards ultimate success.
Mapping business value to APIs will yield a programmable enterprise. An enterprise where collections of easily interconnectable bricks of APIs can be used quickly to build solutions to meet rapidly changing business demands. This is a continuous process, and well understood pipelines of continuous integration, development, testing, and releases can be applied so that innovation continuously flows through to real solutions. Furthermore, being able to control the API definition means that you have complete control over how your enterprise value is represented, rather than the traditional approach where application software vendors determine what the APIs look like.
An API-first design allows you to start prototyping an idea while the concrete implementation happens in parallel (or not at all until a concrete decision is made to implement). Time to value is significantly reduced. Risk of ultimate failure is also reduced since iterations are frequent and small, yielding incremental success in a very granular way. APIs can be repurposed for a variety of unknown future ways with their value growing exponentially over time. Concrete implementations of APIs can be easily outsourced in tightly defined work packages maximizing the best and most affordable skills for the tasks in hand.
The traditional API approach
Let’s take a moment to understand the traditional API approach. Typically a traditional API is forced upon an enterprise by a software vendor and there’s not much you can do about it. You have invested in the software primarily for its user facing functionality and now you have to live with the API that comes with it. The following steps then take place to consume this API, assuming it even has one:
- Understand the API. This often requires wading through lots of technical documentation that is specific to the application software. This assumes a level of technical skill in the software API and the underlying application. These skills may be in short supply or expensive if the application is uncommon or at an old version.
- Validation and testing of the protocols. Having an API is one thing, but knowing how to use it is another. Traditional APIs reflect discrete software functions; not business functions. The task of mapping the software to the business functions lies with the API consumer, and this is no small feat. Multiple very discrete software function API calls may be required in specific sequences to service a single business function. Testing and validating the data and sequence of API calls takes time and can be complex.
- Building and presenting the solution. Having understood the API, built an SDK and written the code to use it, you mount a user interface onto it or tie it to another system and you have a solution. This is typically a point-in-time, monolithic solution that addresses one business challenge. You do have an SDK that might be useful for other challenges though, but now you have to commit developer resources to ongoing maintenance of the SDK.
What is the OpenAPI specification?
APIs are not new, so why haven’t organizations taken an API first approach before? Some have tried but found the complexity and difficulty of consuming different traditional software focused APIs time consuming and technically challenging. A common standard is needed to describe an API. The OpenAPI specification is that standard. It is OpenSource and not tied to any specific integration or software vendor. An OpenAPI specification is a document that describes an API. It can be designed and written from scratch in a design-first approach or exported from an existing compliant API (code-first). Once documented to the specification, the API can be directly consumed by integration platforms and modern application design frameworks.
Three reasons to adopt OpenAPI
The OpenAPI specification mitigates traditional API pain points in a number of ways. Here’s three reasons to adopt it:
1. It’s Open
The OpenAPI specification is not tied to any one vendor. Being open means that it has lots of support from lots of directions. Cloud service providers allow you to directly import an OpenAPI document and then get to work using the API in a matter of minutes. Application design frameworks allow you to import OpenAPI documents and start using the API immediately. Since it’s a standard for describing an API, there are no security concerns since you don’t actually run an OpenAPI document, you use it to self-document an existing API (code-first) or describe a new API (design-first) and then exchange the OpenAPI specification document between consumers.
2. Highly consumable
Conforming to the OpenAPI specification enables a number of very high value activities:
- Interactive web-based API documentation and testing out of the box.
- Rapid SDK generation through Swagger Codegen in most popular languages.
- Direct import/export into integration and application design platforms.
Imagine an API with a hundred API calls each mapping to a valuable function and returning a specific data structure. The task of documenting this so that it can be easily understood is not trivial. By complying with the OpenAPI specification you automatically get the reward of a self-documenting API through what is commonly known as the Swagger UI. From this Web UI you can download the specification document, read each method, understand the schema for the response bodies, and try it out.
The task of building a software development kit in your language of choice against this API is also repetitive and time consuming. With the Swagger Codegen tool you can provide an OpenAPI document and it will generate an SDK against it almost instantly, accelerating you towards consuming the API.
Importing an API directly skips the repetitive steps of consuming the API and fast-tracks you to doing something useful with the API.
3. Currency for an API economy
When enterprises represent their business functions and data as APIs they need a currency to trade those APIs between organizations within and outside of their enterprise. A currency is a leveler in an economy enabling trade. The OpenAPI specification can be thought of as the currency of an API economy, allowing departments and organizations to trade in APIs to accelerate innovation and respond to events in the broader marketplace. The focus shifts away from how to trade towards what to trade and the creation of valuable products and services to trade with. A vibrant and innovative marketplace trading in APIs that represent discrete business values inevitably leads to new innovations in solving business challenges and ultimately differentiates one business from another. This is a true transformative process that amplifies the human contribution in an organization away from the mechanics of doing and towards creating business value.
What about existing applications?
So that all sounds amazing, but most organizations have existing applications that have old traditional APIs or none at all. How can these be equipped to participate in this API-first strategy when they were written before modern APIs existed? The answer lies in harnessing the power of robotic process automation behind OpenAPIs. Using an API to represent a human user’s activity and then having a platform to roboticly drive this at scale overcomes many of the traditional integration challenges outlined previously.
Existing applications can be thought of as asset banks of business logic and data accrued over decades. When viewed in this way it is clear to see that surfacing this value in modern consumable APIs would immediately yield rewards. This is the challenge we have addressed with the AppBus Platform. The platform enables organizations to model existing application screens and controls and then design an automation to service OpenAPI requests against those applications. Since the application modeling is performed by sitting with a business user, the API definition is also business focused and inherently API-first. The resulting API is compliant with the OpenAPI specification so captures all the rewards mentioned previously.