The difference between an API and a connector: When do I use one? 

An API (Application Programming Interface) is a machine and human-readable definition of an access point to a function or service. You never develop an interface, you always design one.

For starters, an API describes the capabilities and behavior of the underlying function or service. APIs cannot be instantiated and have no runtime component. It is like a technical drawing of a pipeline fitting.

To access an API, you need a network address in the form of an URL with its technical definition and its documentation. For example, a self-describing endpoint could be:

“https://api.acme.bank/V1/payment/_oasv3” for the technical Open API definition.

“https://api.acme.bank/V1/payment/_docs” for the human-readable documentation.

“https://api.acme.bank/V1/payment” for the service endpoint

Rest APIs

The modern definition of a REST API is a collection of endpoints that describes a service offered by the API provider. With these APIs, you are describing a specific capability and point towards the service access point. The REST APIs documentation is recounting all its capabilities and behavior. This includes prerequisites, features, failure behavior and examples for the message.

For example, you have a coffee machine in a box that arrives at your home. From there, you will read the user guide to understand how to operate it. This is what an API is for service. APIs are using international standards wherever possible to enlarge their integration capabilities. Even if it is not mandatory, everyone agrees to do so.

Connector description

Connectors are a template for a function and can be seen as unspecific implementation as a service.

A Connector is for an Application what a VPN is for a Network. Connectors can be instantiated and should be a microservice-container in modern architecture. They should only exist for proprietary applications that cannot expose services as APIs themselves.

Connector instances should only be accessed through an API to be part of the modern ecosystem. Connectors should never be used to orchestrate or mediate content. As Connectors have a runtime, they need to be developed, tested and maintained in coordination with the Application. Furthermore, Connectors can mediate security tokens if necessary. Learn how to create successful APIs.

APIs and a Connector: When to combine them

To utilize APIs and Connectors, if you do not have a chance to expose application capabilities directly, APIs start to develop a Connector to bridge the gap. Connector instances can be services themselves and the connector endpoints should be described with APIs.

Describe access points to services with APIs whenever this is possible. This ensures that exposure of an API through API Catalogs will bring about re-use and adoption.

In the end, APIs and Connectors are not enemies in integration. They bring about great benefits to the consumer by combining access to legacy and modern systems in a changing technological environment.