FAQ

Can the foundation be included as a dependency in the API integration?

Foundation does not contain actual product features, but is an agility layer.

The foundation controls the technology and provides development tools by introducing support for best practices, patterns and implementing many useful technologies.

Furthermore, foundation provides support for technical configurability which is now integrated with our CD/CI lines.

This is especially true in version 12 (in beta, which will be presented in 2024W1) in which the foundation sub-module can even be launched without a specific database and without the need of any UI (again, UI is an opportunity, not a must).

Therefore foundation is a good opportunity to build any type of artifact, even integration ones. Obviously it is not an obligation, but it could be an advantage because there is a team that defines evolutions, management, security and support.

It can therefore be a dependency of the integration project also because we have many developers who know how to exploit the advantages.

Therefore foundation can hopefully be a dependency of the project implementing the API integration layer.

Architecture: will the API integration be stand-alone or a project dependency?

The api integration, as we are thinking it is naturally an independent process, speaking with the FSM through REST APIs.

It would be a different artifact, deployable or not deployable on convenience, and possibly multi-tenant. 

My suggestion is to use a single approach on deployment, so that even in SaaS or On-Prem the running architecture would be the same.

Therefore I do not see project dependencies (almost no expert dependencies) in the imminent future.

Anyway, thinking on a good maven modularization, the best strategy would be to implement the Integration Layer as a generic Jar Module, usable by a standalone app as a core library or by any other product runtime, supporting different strategies of deployment.

Extensibility: current proposal – an “extension” map in the interface that can contain any type of object

I think the question refers to the extensible data-model.

It's a feature in progress... not ready at the moment. This refers to the possibility of expanding the set of properties of an entity in a way that can be configured in the product and without writing or re-deploying any code. To do this, with the Extensibility Architecture (Magnolia) team we are already foreseeing the possibility of hosting an extended set of properties within each entity, in the data model and in the communication model (json). This tends to mean the use in FSM of objects that are not static but based on a sort of Dynamic Object (DynO).

The use of the foundation integration layer can also take advantage of this type of implementation, thus facilitating communication with extensible data types. Communication standards in this sense are about to be published in the Extensibility Framework document.

Extensibility: use events/business tasks? (depends on the first 2 points, if this is not possible what alternative do we have?)

What has been said is correct. You can use tasks but you will not have a DB to store anything. The Business Events probably will be useless, because there will not be a sort of augmentation of the behaviors in dependence of the tenant.

The behavior will be the same for every tenant, and in the case of customizations of the integration flows, some further orchestration services will be implemented in a different custom layer.

Extensibility: how to pass custom information (“extension” map) to private APIs (POST and GET)

Already answered before. The REST contract force the extension properties (I/e dynamic properties) for any entity.

Talking about Entity IDs I’ think it is a virtually worthy strategy not to public Ids in the integration APIs. But in my experience it is not ever possible. Sometimes also a different legacy component need to store some our entity Id in his DB, just to recall it later…we will se.

But there’s another big reason tu publish ids. It is very unlikely to refer to a resource without an ID, because the ID itself is the way by which every reference to an entity in the REST paradigm is built.

Package structure: do we use common objects even cross-domain or does each domain have its own (for example Address in the Assets and Users domains)?

I think that the integration layer should enter as little as possible into the management of entity contents.

An Address is an Address, possibly without knowing how to manage the various properties of the address. The same goes for a User, probably except for knowing that a user needs a sub-entity which is the Address, and knowing where and how to retrieve/manage it.

Consequently, the implementation of the Address in the integration layer must be minimal and at most generic in order to accommodate all the properties of the extensible application layer, but examining only the parts that require orchestration. Speaking in hyperbole, the Address could be a simple property map or even a json. With this approach, the need to centralize the modulation of an entity is somewhat eliminated.

In any case, if it is useful to do so, in my opinion sharing the model can be a valid strategy.

Maven module structure

To be defined by the architect of the IL.

As I said before, to be very flexible it would be a good strategy to implement the Integration Layer as a generic Jar Module that is possibile to insert as a dependency of the product, for some future proof deployments (some on-prem scenarios with specific constraints).

Composition: can an integration API be composed only of private APIs or also of other integration APIs?

I agree with what was answered.

It is possible and most of all it can be a good strategy for a Custom Integration Layer (when the FSM has been customized or the requirements of the integration is different within a specific customer scenario). In fact when we will be asked for a redefinition of an integration flow, it would be nice to go with a composition pattern, putting together the custom process with the standard process

Authentication: token / tenant mapping - how do you determine the base URL of the tenant from the token?

The token, usually an OAuth token or generally speaking a JWT (Json Web Token) contains a specification of the tenant. These specification can drive the decision of the url-endpoint of the dedicated services for that tenant. There can be many ways to implement this association, but the one I suggest is to use properties fetched from somewhere…This is where the admin console could come in aid…but at the moment we can easily think on using the technical configurability features of the foundation that are based on properties, and to feed them from the CD/CI.

Authentication: with which user to call the private API? Token forward? Is the internal user the same as the external user?

Token forward I think it should be the right strategy. Therefore the internal and the external user are the same. 

Possibly the token could only be validated, to protect against Cross tenant attacks, but this will discuss it at the right moment. 

The responsibility for the validation is the gateway…but if necessary (on-prem?) we will be able to validate it with the foundation.

The main idea is that the orchestration itself doesn’t need an authentication.

The individual private services will accept or reject the individual steps of the integration flow.

Permissions: how to manage permissions in API integration?

I agree with what has been said.

The permissions remain in charge of the backend application, dealing with the RBAC implemented model.

External libraries: How do you decide whether a library can be included in the integration API?

If your dependency is the foundation, it will provide a lot of technology under the feet so that probably you won’t need others. After all, you are implementing an integration…nothing else.

In that case the foundation is already checked against security attacks and it receives the green-light from the security team. You will be in safe hands.

As you can see we are thinking on an integration layer that doesn’t need too much orchestration complex patterns to work with the Fsm services. Probably you don’t need support from dedicated libraries to implement what needed, but in case we can think on a dependency with tools like Apache Camel or something like that. So, let’s start with no dependencies and upon special needs we will see what to do.

Architecture: HATEOAS / SOA?

HATEOAS is nice but we decided not to include it on our Extensibility Architecture because of the complexity. Moreover in my opinion it needs to bring a very complex knowledge of the whole solution inside each module domain. Furthermore, it is difficult to support it with a rapid evolutionary step of private APIs, and it would eventually turn into a brake.

Transactions/data consistency: Implement compensating transactions from scratch or are there libraries to handle them?

Just today we discussed a lot on this point. We think there should not be a strong need for such type of compensation transactions inside an integration API.

The reason is that when two domains are so closely related that they do not allow a sequence of non-transactional steps, then these domains have only an abstract value and concretely require the product to expose the transaction logic with an API, perhaps a dedicated Intent.

This is because we don't want the Integration Layer to be a re-implementation of the product business logic.

If there are coupling logics that have not (yet) been removed, they certainly cannot even be duplicated in a second artifact.

Anyway, Claudio S. already agreed on supporting you for unforeseen complex cases.

Transactions/data consistency: how to manage compensating transactions in the event of an application crash?

Same as before

Competition: should it be managed in the integration API or in the private API?

I think on the private. Let Claudio S. help you on such cases.

Logging strategy?

Agree on standard logging strategy, that will start from the Foundation (with tools and APIs) and go through the infrastructure involving transactionId e spanId log properties