Business Innovation Manager KBC
KBC Enterprise Architect
In the first part of our series on integration options, the focus was on different forms of integration, including APIs, widgets and URLs. Each of these forms allows you to offer the same functions, e.g. making a payment, making items available for sale, etc. These forms all have one thing in common: one party offers a function so another can use it. You can choose a different form of integration depending on the degree of responsibility that each partner is willing to take on. This time around, we're going one step further. We're digging deeper into the principle of layered architecture and applying it to a wide range of applications. We allocate the responsibilities held by an application over different ‘layers’ that are connected to one another.
The layers of an application
The top layer is the presentation layer. This is the layer that the application user sees and works with. The logic with which this layer is built helps the user to work with the application without any interruptions. An example is information field validation, where the user receives feedback immediately on what needs to be changed, e.g. entering a date of birth in a certain format, the language settings of an application, or a photo gallery that the user can click through.
The middle layer is the business layer. This layer contains "business logic", and is the link that connects the other two layers. Specifically, business logic means the rules with which you run your business – translated into IT logic. This includes specific calculations and/or checks, e.g. calculating the amount of commission paid on a sale or checking whether a party is permitted to have access to certain information.
A good example here is a bank that asks for a pay slip before you can receive a loan. This is a business rule that is translated on a technical level into the business layer. In other words, the business layer controls the presentation layer: what you see in the presentation layer is governed by the rules defined in the business layer. Mandatory fields marked in red in the presentation layer are like this because of the logic inherent to the business layer.
The bottom layer is the persistent layer, also known as the data layer. This is where all data is stored, whether manipulated by the business layer or not. It constitutes the link between the application and the underlying database(s) used by the application. In principle, the data layer itself does not contain any logic. It is more like a notebook in which the business layer writes.
This is interesting, because every type of integration takes a different approach to this. The layer not contained within the integration format is therefore entirely under your control and is your responsibility.
The role of API consumer and API producer
The most common type – the API – exclusively offers business logic. The person who creates and offers the API is the API producer. The API consumer is the partner that uses the API and makes it available to their customers.
For APIs, responsibility lies with the API consumer to take the requisite steps to convert the API into a screen for their users. This means that the partner who makes the API available creates the presentation layer with which their users interact.
API contract or Swagger
The dividing line between consumer and producer for this integration is described in the API contract or Swagger. This sets out in detail where the consumer's responsibility ends and where the producer's responsibility begins.
A technical contract or Swagger is written in a specific format that sets out what the API needs in terms of information to be able to perform its role and which information you can expect to receive in response. A Swagger purely describes the format in which the information is sent back, not how the underlying business logic interacts or how its behaviour is defined.
The main benefit is is that you, as a consumer of the API, are responsible for the presentation layer; you decide what your customer sees, and what actions they have to perform/not perform in order to use the service. The consumer is responsible for completing the API correctly and defining it in the Swagger. The producer of the API is obliged to respond appropriately to the consumer's request. The producer is also responsible for the data layer.
A contract of this kind may appear simple at first glance, but there is some margin for misinterpretation when it comes to determining who is responsible for what. The Swagger sets out what you can request from an API and what the API can give back. However, it does not describe the ‘behaviour of the API’.
Take setting up a loan simulation API as an example. This requires two fields: the purchase amount and the purchaser's own contribution. The Swagger does not describe how the API responds if the purchaser's own contribution is higher than the purchase amount or if one of the two figures is negative. It does state what response you will receive from the API, i.e. whether you are eligible for the loan or not.
Want to find out more about API behaviour? These underlying business rules are set out in the API documentation. This example involving the loan simulation is a very simple one. The potential of the behaviour is much greater when working with more complex APIs, e.g. where saved data has an influence on the outcome produced by the API.
The response given by the API to the consumer is called the API's external behaviour. The internal behaviour is described in the documentation, so that you, as the consumer of the API, know what to expect.
The iframe, widget and SDK can be considered part of the same package. These integrations go a step further than the business logic layer and offer a graphical interface on top. This interface can be 'embedded' in the interface used by the consumer, which speeds up the implementation process considerably. In most cases, the graphical interface supports the interactions performed by the user, meaning it is part of the presentation layer.
As might be expected, the responsibilities between the producer and consumer are different than with an API. These types of integration are also subject to a contract – a manner in which they can be initiated by the consumer's software. In addition to offering a graphical user interface, they are able to issue a result to this software. This is very similar to the contracts to which an API is subject. The main difference here is the graphical interface and the role it performs.
An integration example: maps widget
When setting up this type of integration, the consumer expects it to offer certain functions. As a user, you may, for example, expect to have access to a maps widget allowing you to zoom in or mark a specific route. All of this is part of the external behaviour of the widget, which the producer of the widget is responsible for. For these types of integration, the producer is therefore responsible for the presentation layer and the business layer. The drawback for the consumer of this type of integration is that they can no longer determine what the end customer sees or how they see it.
Impact of integrations
Implementing an integration has a certain impact on the environment in which it is done. Ensuring that this impact remains 'consistent' is something that the producer of the integration should take into account.
When choosing between the different types of integration, it is important to know which responsibilities you are willing to take on and which ones you are not – both when developing and when maintaining the integration. It is also good to know that the data is ultimately in the persistent layer at all times – meaning it is always controlled by the producer behind the method of integration.