APIs, User-Agents, and Interaction Patterns
This blog provides an overview of the service
call patterns typically found within any large scale, multi-channel interaction layer. Here we define a service call as
any interaction with an API endpoint. That interaction is generally a request that expects a response and often times requires the use of more than one API endpoint to
complete the client / user-agent request. Despite the need to make several calls to multiple APIs, the overall processing will generally appear to
the user to be synchronous, i.e. a single request. In this paper I attempt to highlight the requirements and constraints of each pattern and the affect on the the users experience.
What is an interaction layer?
An interaction layer solves a general many to many problem that occurs within many fields of software intensive systems. The interaction layer specialises in user interface to system processing and although similar to enterprise integration, which also involves routing and transformation, it is fundamentally different because it involves a person. Interaction from a user generally requires a response; furthermore that user can understand the meaning of a response, whereas integration between two systems does not generally require a response and a system cannot understand the meaning of unexpected responses.
 |
| Figure 1 - Logical interaction architecture view |
Interaction Layer Implementation
Whilst the diagram in Figure 1 - Logical interaction architecture view provides a good basis for understanding the elements of the interaction layer, it is sometimes more meaningful to see how the system might be implemented with components that handle the transformation, routing, and description of the model. See Figure 2 - Interaction Framework Components. NB - this is the component view of the IRIS implementation of an interaction framework.
 |
| Figure 2 - Interaction Framework Components |
This pattern describes a scalable architecture designed to address a requirement where a resource must be created in 2 or more resource managers, a resource must be consistent across 2 or more resource managers, or a validation rule can only be processed following the completion of a transaction in another resource manager. E.g. Anti-money laundering, Master data management, ATM or any over the counter style transaction where we must process the full value chain. To scale with this requirement we must not serialise the transaction across two resource managers or introduce a two phase commit.
 |
| Figure 3 - transactional service orchestration |
Figure 3 - transactional service orchestration
1. User-agent requests create or update operation; waits for a response
2. Interaction layer requests create or update operation
3. Interaction layer immediately begins to poll for a result
4. Two one-way message between resource managers
This pattern describes a scalable architecture designed to address a requirement where a resource must be created in 2 resource managers and there is no transfer of risk. A resource must be consistent across 2 or more resource managers, or a validation rule can only be processed following the completion of a transaction in another resource manager. E.g. order management. To scale with this requirement we must not serialise the transaction across two resource managers or introduce a two phase commit.
 |
| Figure 4 - transactional service no orchestration |
Figure 4 - transactional service no orchestration
1. User-agent requests create or update operation; waits for a response
2. Interaction layer requests create or update operation
3. Interaction layer immediately begins to poll for a result
4. Single one-way message between resource managers
This pattern describes a scalable architecture designed to address a requirement where a resource must be validated before being created in a resource manager. E.g. a business validation with an external service such as an address. All user-agents and services exposed share the same validation logic, the call to the validation service is permissible as it does not perform any modification and therefore does not serialise the request across two resource managers or require a two phase commit.
 |
| Figure 5 - validate and commit |
Figure 5 - validate and commit
1. User-agent requests create or update operation; waits for a response.
2. Interaction layer validates the request with the external service
3. Interaction layer requests create or update operation within a single resource manager.
This pattern addresses a similar requirement to the ‘validate + commit’ pattern, and describes a scalable and low latency architecture where a resource is validated in multiple resource managers. E.g. a business validation with an external service such as an address, and the validation of the financial transaction. All user-agents and services exposed share the same validation logic, the validations can be performed in parallel.
 |
| Figure 6 - validate |
Figure 6 - validate
1. User-agent requests validation operation; waits for a response.
2. Interaction layer validates the request with the external service; in parallel validates the request with the resource manager.
This pattern describes a scalable architecture designed to
address a requirement where a screen is enriched with some external data to
make a decision or improve the data entry.
E.g. estimated rate, an address finder, or a dynamic screen adaption
based on metadata.
 |
| Figure 7 - enrichment with javascript library |
Figure 7 -
enrichment with javascript library
1. User-agent
requests enrichment directly from the client; waits for a response.
2. User-agent
requests create or update operation; waits for a response.
3. Interaction
layer requests create or update operation within a single resource manager.
 |
| Figure 8 - enrichment with interaction layer routing |
Figure 8 -
enrichment with interaction layer routing
1. User-agent
requests enrichment from the interaction layer; waits for a response.
2. Interaction
layer requests enrichment from external service
3. User-agent
requests create or update operation; waits for a response.
4. Interaction
layer requests create or update operation within a single resource manager.
This pattern describes a scalable architecture designed to address a requirement where a screen is filled with data from multiple sources. E.g. a single customer view, orders and holdings view, and complex composite screens. To scale with this requirement we adopt the constraint that we only mashup whole resources, we do not aggregate results into rows.
 |
| Figure 9 - mashup interaction layer |
Figure 9 - mashup interaction layer
1. User-agent requests data; waits for a response.
2. Interaction layer issues requests in parallel with all data providers and return embedded resources within expanded links. See HAL+JSON embedded resources for example.
NB – user agent waits at least as long as the slowest response.
 |
| Figure 10 - mashup ui layer, controlled by interaction |
Figure 10 - mashup ui layer, controlled by interaction
1. User-agent requests resource; immediately renders screen; issues further requests by dereferencing links that were provided by the interaction layer.
2. User-agent requests resources in parallel; renders as available
3. Interaction layer issues requests to data provider
NB – rapid time to first byte (something displaying on the screen) provides an optimal user experience; see data as soon as it becomes available.
The following anti-patterns are common solutions to some of the
above requirements that are ineffective or non-scalable.
This pattern describes a non-scalable architecture designed
to address a requirement where a resource must be created in 2 or more resource
managers, a resource must be consistent across 2 or more resource managers, or
a validation rule can only be processed following the completion of a
transaction in another resource manager.
E.g. Anti-money laundering, Master data management, order management.
This approach does not scale because it ties up scare resources in the
resource manager, we serialise the transaction across two resource managers and
require a two phase commit to remain consistent.
 |
| Figure 8 - Transactional update with call-out and two phase commit |
Figure 8 - Transactional
update with call-out and two phase commit
1. User-agent
requests create or update operation
2. Resource
manager requests create or update operation
