OpenAPI and the API Economy
OpenAPI is a topic that is exponentially growing in relevance as APIs (Application Programming Interfaces) continue to change core areas of our everyday lives. Here is a perspective and some insights.
When we talk about the future we often talk about sci-fi such as humanlike talking robots. While it is intriguing and legitimate to speculate on the future, the reality today is that robots are only good if they have been trained in very specific things. The way to the future is made in smaller steps. It is a gradual increase in digitalization and interconnectedness of society. A way to measure this is by the number and utilization of APIs available. They are the building blocks of the future.
APIs have changed our everyday lives in the following core areas. Logistics APIs are behind the "Your package is ready" phenomenon, as they connect sellers and consumers via online trading platforms. Internet marketing APIs are behind the online advertising phenomenon by connecting advertisers to specific consumers via internet browsers, search engines and apps. Internet services APIs are behind the "share on social media" phenomenon as well as "cloud computing" connecting individuals and organizations with online IT infrastructure and applications.
Numbers from ProgrammableWeb give an indication of the growth in APIs. It all seemed to begin around 2005 and grow exponentially from there.
Looking ahead, the next core area of our daily lives that will be shaped by APIs is undoubtedly finances and payments. This is also indicated in the numbers from ProgrammableWeb.
In Denmark we are actually a bit ahead with regard to payments compared to most other countries, in that we have already gotten used to instant payments with the MobilePay app. New alternatives have also been evolving in other countries and globally e.g. Paypal. However, that is just the beginning. In order to keep up with the development, the EU released the PSD2 (Payments Directive) which took effect with the new "Betalingsloven" in Denmark in January 2018. The law requires all banks to create open APIs which enable third parties to access account information and make payments directly. This means that companies can now establish themselves in this industry without relying on any agreements with banks or with Nets (historically the monopolist in Dankort payment processing and clearing in Denmark). For the same reason MobilePay is also now changing from being reliant on the card payment scheme (Dankort) to instead using APIs to make direct transfers between user's bank accounts. New players will come and application based instant payments (not using cards that have up to fours days of delay) will become the norm.
With APIs driving key developments in society and being vital to many businesses the ability to present and document the APIs becomes a point of interest. In some cases the API documentation is the outward technical face of the company's product. It is where architects and developers look before they advise decision makers. It should not be reliant on personal contact. Having a good way to enable the audience to explore the API may drive adoption of the API or new API features.
The best practice for how to do things in the IT industry today if you change or create an API is to use the OpenAPI specification to define your API. Part of the beauty of using the same definition of APIs is that tools are now available that visualize and navigate and in some cases support direct interaction with such APIs (for learning purposes using a sandbox environment). API documentation has the form of an application unlike traditional .pdf documents.
I was recently part of a project at Itera Denmark (https://itera.dk) to build a unique API Explorer application for a customer by mixing and matching functionality from the leading API applications, namely SwaggerUI and Redoc. Both are open source. We decided to use the SwaggerUI plugin system and to modify the Redoc source code (their open source license allows free and unlimited commercial use) and then combine the two.
SwaggerUI, the custom plugins and custom components are packaged as one modern node.js application using well known npm packages for functionality and compilation. This makes the application platform agnostic and as a result it can be deployed on all major platforms - including as a microservice (e.g. docker app). The user interface consists of modular components that are built in React.js. Anything can be customized according to needs by making changes to the mix of existing and new components. The application is a SPA (Single Page Application) and is illustrated further below.
At the top of the application there is an overall description of the API. Content formatting is possible using the best practice Markdown syntax. The headers in the description become available as links in the lefthand navigation as shown below.
The navigation tells you where you are and provides quick access to the rest of the API (see below). All navigation is instant because it is an SPA.
The application visualizes examples of parameters, sent and received payloads and code. It can also be used to try out functionality (authenticating and making calls to sandbox environment) based on settings in the API definition file.
The solution offers flexibility to our customers given that the application is built around widely adopted standards, is platform independent and fully customizable. As a result it can be applied to any API that follows the OpenAPI standard, can be deployed in different technical infrastructures and already contains a lot of functionality so they will not have to start from zero.
With that I hope you have a better feel for what APIs are about. Whether you have a business need for API related services or you are a developer, you should have enough inspiration to get going with your project. Happy API development!