How API Schemas Are Making Connectors Obsolete David Brown October 13, 2020 Specifications like OpenAPI are providing a solution to outdated connector issues by providing the option to create machine-generated integration services on demand, writes David Brown, founder of TORO Cloud. Connectors, as used by an Enterprise Application Integration (EAI) platform or iPaaS, could soon be made redundant as these platforms start to replace them with machine-generated services driven by API schemas. The benefit to users is that they are no longer reliant on the platform to offer a connector for the API they would like to consume, providing the user greater independence to integrate any API they choose. When a developer wants to integrate a web API with another system or application, they typically have two choices. Either laboriously write the code by hand — or — use an application integration platform, often referred to as an iPaaS. Traditionally, integration platforms have provided a unique connector for each and every API that the platform supports. These connectors facilitate communication between the platform and a third party system or API. As customers of these platforms were dependent on the platform offering a connector for the API they wanted to integrate, it meant there was a race of sorts between vendors who could offer the most connectors. But what if the vendor doesn’t provide a connector for the API you would like to consume? Or, what if their connector is out of date? API description languages like OpenAPI provide vendors of integration platforms a solution to this problem that can eliminate the connector and allow the user to consume the API directly with dynamically generated integration services. What Is A Connector? EAI platforms utilize connectors to allow communication between the platform and an API. The connector wraps the API in a language that the integration platform can understand, allowing the API to be accessible by that platform’s users. EAI platforms make end-users more productive by providing visual, declarative models for describing the components for integrations. These components include endpoints, protocols, data formats, data transformation, and workflows. An integration platform can dramatically reduce the grunt work required that would otherwise have to be coded by hand to perform those repetitive functions. It also reduces the chance for human error and produces integration services that are easily reusable and discoverable. Each integration platform has its own way of describing these declarative models for integration. A connector is a wrapper that enables the integration platform to translate each API’s operation to a format that the platform understands. The Problem With Connectors Connectors are typically written by hand. They are timing-intensive to develop, and, as a result, expensive to write and maintain. This limits the number of connectors that a vendor can viably produce. Given the economics, connectors are created for the most popular software vendors first. APIs from smaller vendors and specialized lines of business applications may not be supported at all. Given the proliferation and exponential growth of APIs, it is impossible to keep up with the API publishers when writing connectors by hand. In addition, API providers frequently change their APIs, especially when the services are still maturing. This happens more often than most people realize. Some publishers are less disciplined about correctly versioning changes to their APIs to ensure that breaking changes are only introduced in major updates. As a result, minor changes to an API can break a connector. Ideally, it should be possible to continue using the connector with the last supported version of an API. However, in practice, if the API does not use disciplined versioning practices, you may be forced to wait for an update to the connector to accommodate the breaking change. Meanwhile, the API you are consuming may have just released an operation you’ve been eagerly anticipating. If the connector you’re using doesn’t support the new function, then you are again dependent on the vendor of the EAI platform to release an update to the connector. The solution to these problems? API schemas. The Evolution of the API Schema With APIs, we talk about making them discoverable. By this, we mean making it simple for a consumer of an API to understand the APIs purpose, operations, protocols, authentication, how to format a request, and the structure and payload of a response. The most common way to achieve this is web-based documentation. Such documentation targets human consumption, including code snippets for developers working in various programming languages. Ultimately, it assumes that a human will be the one to interpret the documentation and build the services required to consume the API. Some API publishers produce a Software Development Kit (SDK) to make it easier to consume the API in a given programming language such as Java or .NET. An SDK makes it easier to consume an API when writing an integration by hand. However, it doesn’t change the fact that an integration platform would have to produce an SDK connector. While most API publishers provide some form of web-based documentation, relatively few provide an SDK. API Schemas and Machine-Generated Services API description languages were designed to solve the challenge of making an API discoverable with structured documentation that is readable by both humans and machines alike. The output of an API description language, the API schema, is produced in JSON or YAML and describes an API in a standards-compliant way. API schemas create machine-readable and structured documentation that allows an API to be more discoverable. An Enterprise Application Integration platform can build machine-generated services for each API operation on demand by reading an API schema directly. If an EAI platform can read an API schema and generate integration services from it, there is no need to wait for the integration platform to support a specific API. So long as the API provides an API schema, the platform should be able to consume it. If the API changes, then you can simply import the updated API schema, generate new services, and start consuming the new operations immediately. Like most emerging standards, when the first API description languages emerged, there wasn’t a clear-cut consensus on a format that would become the industry standard. In the beginning, there were several competing standards, including Swagger, RAML, Blueprint, and WADL. While some of these formats are still in use today, the API definition wars have largely been won by the OpenAPI specification. This standard emerged after Smartbear donated the Swagger specification to the OpenAPI Initiative and gained the backing of practically every major software vendor in the API space. After the standardization around OpenAPI, it was only a matter of time for tooling to mature to support the standard. Nowadays, there are tools to design an API visually, automatically generate an OpenAPI schema, generate web-based documentation, create API explorers, and many other areas. There are even free tools available to reverse engineer a standards-compliant OpenAPI schema from regular web-based documentation. So, even if an API publisher doesn’t provide an API schema, anyone can produce their own. Likewise, integration platforms are starting to consume OpenAPI schemas and build machine-generated integration services on-demand bypassing the need for a connector entirely. Conclusion Digital transformation initiatives and the API economy are driving the adoption of APIs. The resulting exponential growth of APIs has made it increasingly necessary to ensure there is an industry-standard for machine-readable documentation. The resulting standard, OpenAPI, has enabled vendors of Enterprise Application Integration platforms to eliminate the old manual method of using connectors. Instead, these platforms can generate machine-generated integration services on-demand to facilitate communication with APIs. When an integration platform eliminates connectors and supports machine-generated integration services, it empowers APIs consumers, and they become more agile. They have greater freedom of choice to use an API based on the value it offers rather than whether their integration platform can support it or not. Finally, they can respond to changes to an API they are consuming without waiting in anticipation for the vendor of their integration platform to release an update supporting the change.