Integration API's are different

In the current hype around API’s it amazes me that the distinction between application API’s and integration API’s gets little to no attention. It can however be of vital importance.

Let’s examine this with a common example. On the left side you see Lois, who is working for the Logistics department, and she is responsible for Order management of incoming orders. To be able to do her work, Lois uses the Ordering System. The Ordering system is the system that is authoritative – the System or Record – for the Ordering process. All incoming orders are created, updated, deleted and processed in this Ordering system, and through a front-end application Lois uses API’s to create, modify, delete or process her incoming orders.

On the right side you see Fiona, who is working for the Finance department, and she is responsible for Invoice management of outgoing invoices. To be able to do her work, Fiona uses the Invoicing System. The Invoicing system is the system that is authoritative – the System or Record – for the Invoicing process. All outgoing invoices are managed in this Invoicing system, and through a front-end application Fiona uses API’s to create, modify, manage and delete outgoing invoices.

Figure 1

Of course Fiona does not create new invoices out of the blue. She needs a reason to create a new invoice. An incoming order is a good reason. That is Lois’s responsibility. But she is not responsible for creating invoices. She can ask Fiona to create an invoice for her incoming order.

Exactly the same reasoning applies when implementing the processes with API’s. The Create, Update and Delete API’s are Control API’s. In the Logistics domain the Ordering user interface can take control of the Ordering system with these Control API’s. In the Finance domain the Invoicing user interface can take control of the Invoicing system through their Control API’s. The Ordering system is not responsible for creating invoices, the Invoicing system is. Therefore we cannot allow the Ordering system to take control of the Invoicing system by allowing it to use its control API’s. (See Figure 2)

Figure 2

Since we cannot allow the Ordering system to take control of the Invoicing system, we must allow the Ordering system to ASK the Invoicing system to perform some process(es). For example: the Ordering system cannot create a new invoice but it can ASK the Invoicing system to create an invoice. We can implement this on authoritative systems with Request API’s, that allow non-authoritative client systems to request authoritative systems to perform actions for them, as shown in figure 3.

Figure 3

It is important to be aware of the difference between Control API’s and Request API’s. Control API’s are used within an application or system. They are used in (user) interfaces for actors that have the authorizations to control the processes and data that the Control API’s give them access to. This is most often the case in client-server architectures, which falls in the realm application architecture. That is why we can also call them Application API’s.

Request API’s are used at the boundaries of an application or system. They are used by actors outside the business domain, that do not have the authorizations to control the processes and data of the application or system. Instead the Request API’s give these actors the opportunity to request the application or system to perform some action for them. The business domain crossing aspect of Request API’s make them fall into the realm of integration architecture. That is why we can also call them Integration API’s.

If you are currently using API’s in application integration, I suggest that you carefully review them again. If you fail to make the distinction between Application API’s and Integration API’s you may unwittingly find yourself in a lot of trouble.