APIO Multi-AS Concepts and Configuration¶
High level concepts¶
The simple deployment of an APIO is when it manages one Application Server.
A customer setup could contains several AS. The APIO can handle this mainly in 2 configurations:
One APIO instance is deployed by AS and the customer makes sure that the API traffic reach the correct APIO. It is the recommanded set-up when each AS is independent and could have the need of very different settings.
One single APIO instance is deployed ans manages all the AS. This set-up is used mainly when the presence of several AS is due to load but they offer the same services and therefore need the same settings. This is what is called the multi-as set-up.
In the case of the multi-as, several settings will control the way the APIO will manage it.
It must be noted that the multi-as is provided from release 1.9.0, previous releases contains partial support of it.
The APIO logic relies on two assumptions:
A Tenant is present in only 1 AS
The migration of a Tenant to an other AS is possible but is an execptional operation and it could requires some manual operations to inform APIO of the change
Identification of the AS for an API call¶
Login Phase¶
The user must be linked to the correct AS (aka main server) in order that some APIO features can work correctly.
This linking will described below but it is a time consuming operation. Therefore after a first successfull login the link user-AS will be inserted in APIO DB and be re-used in all next login operations to speed it up.
The APIO supports several mechanism to identify the link user-AS, the usage of one of several of them is partially based on configuration and will depend on what the operator owning the AS will expose as interface.
All these mechanism is based on a set of configuration objects called Backend that represent an AS and its different properties (mainly connection information).
The first mechanism is based on the availability of a “User Location” API that the APIO can call and that takes as input parameter the user id and returns the AS name. If such API is available it is used to identify the correct Backend and perform the login operation directly on that one.
The second mechanism will try to log, sequentially, the user on each Backend present on its DB and will stop in the first success. It will consider therefore that it is the Backend (AS) hosting that user.
In that second configuration, there could be a complication: the Backend could proxy the login request internally between AS and therefore the selected backend is not always the good one. If this is the case, we have two possibilities, that are not mutually exclusive:
a “Tenant Location” API is available and the APIO can use it to retrieve the AS managing the user based on the Tenant Id present in its login answer (available for End User, Group Admin and Tenant Admin)
the operator performs a pre-configuration of each Tenant in APIO DB (TenantData object), before any user of that Tenant perform a login, to link the Tenant to a Backend in APIO DB.
It must be noted that even in case of availability of the “Tenant Location” API the APIO will store the link Tenant-Backend as soon as it knows it and will use it for th enext checks to reduce the number of access to the “Tenant Location” API and its impact on performances.
A mix of the different mechanism is of course possible.
The behaviour of the login phase is controlled by the following configuration settings:
"MULTI_AS_LOCATION_API": false,
"MULTI_AS_TENANT_API": false,
"PROVIDE_BACKEND_INFO": false,
- Explanation of the parameters:
MULTI_AS_LOCATION_API: if true, the Location API will be used to locate a user based on his user id. The default value is false as in basic setup, with only 1 AS, it is useless.
MULTI_AS_TENANT_API: if true, the Tenant Location API will be used after a successful login in order to confirm the backend. The default value is false as in basic setup, with only 1 AS, it is useless.
PROVIDE_BACKEND_INFO: If true and if the user profile has a main_server then its name will be provided. Default is false as it is disclosing some network set-up information and in basic setup, with only 1 AS, it is useless.
Be careful that the 2 types of Location API require that they are available and that they are configured in the Backend objects configuration (not part of this guide).
Other API Call, not multi-as user¶
In case a user is not a multi-as user, each API call other than the logic will use the backend reference that has been stored in his APIO profile to make the call towards the correct AS.
Nothing specific has to be configured for this, it is the basic behaviour.
Tenant or below API Call, multi-as user¶
When a Multi-As System Admin user is trying to reach an endpoint at Tenant level or below (i.e. when a tenant_id is present in the url) the APIO will check if there is a TenantData object for that Tenant with a backend reference.
If it is the case, it use that Backend to handle the call.
If it is not the case and the “Tenant Location API” is available in his profile it will use it to locate the Tenant and create/update the TenantData object in APIO DB to have it available for the next call.
In case the Backend hosting the Tenant can not be found (unknown Tenant) or the multi-as user is not allowed to manage the related AS, a 400 error message will be returned with the error code 61 (NO_BACKEND_AVAILABLE) and error message “The backend requested for this request does not exist or is not in your profile”
System level APIs, multi-as user¶
We have 3 cases for this.
The first case is the access to AS properties (such a NCOS, time zones, …) in that case the AS where the request will be sent will be defined in the following way:
If there is field backendName or a field backendExternalName in the input data, the APIO will search for his DB for a Backend with that name and use it is found (if both a re provided, only backendName will be used).
Otherwise the main backend of his APIO profile will be used
Note that if a backend is speficied in input data but does not exists or is not allowed for this user a 400 with the error code 61 (NO_BACKEND_AVAILABLE) will be returned
The second case is the Tenant creation.
If there is field backendName or a field backendExternalName in the input data, the APIO will search for his DB for a Backend with that name and use it is found (if both a re provided, only backendName will be used).
Otherwise if a default Backend is defined via the settings MULTI_AS_DEFAULT_BACKEND_FOR_TENANT
Otherwise the main backend of his APIO profile will be used
The behaviour of the create Tenant API is controlled by the following configuration settings:
"MULTI_AS_DEFAULT_BACKEND_FOR_TENANT": "MyBackendName",
- Explanation of the parameters:
MULTI_AS_DEFAULT_BACKEND_FOR_TENANT: for Tenant creation, if a value is defined for this settings and there is no backendName and backendExternalName in the input data, this settings will be used as backendName. The default value is nothing configured.
The third case is the search APIs at System level:
If there is field backendName or a field backendExternalName in the input data then the search will be performed in that backend only (with a 400 with the error code 61 (NO_BACKEND_AVAILABLE) if the requested backend does not exist).
Otherwise each backend will be searched sequentially and the results will be merged in a single final result.
In both scenarios the backendName and backendExternal name will be added in each element of the answer of the APIO has been configured in that way.
It must be noted that responseSizeLimit will not necessarily be honored in multi-as searches.
The behaviour of the search APIs is controlled by the following configuration settings:
"MULTI_AS_BACKEND_IN_SYSTEM_SEARCH_RESULTS": true,
- Explanation of the parameters:
MULTI_AS_BACKEND_IN_SYSTEM_SEARCH_RESULTS: if true, the backendName and backendExternalName of the AS hosting the item will be added in each element of the answer. The default value is true as by default a multi-as user is allowed to see what backend is used.