i2Rest Server Architecture
Contents
i2Rest Gates
i2Rest Server is a high-performance multi-threaded server which has three separate "Gates" allocated for processing requests of various types. Each gate itself is a server with its own listener, internal queue for incoming requests, and a number of "worker" threads to process this queue. Gate servers can communicate with each other and they have a shared memory with common resources.
|
Main Gate - endpoint to communicate with common clients, Sessions Gate - endpoint for sessions, |
Each Gate has a separate listener, which can serve requests with HTTP or HTTPs protocol over TCP/IP or Unix Sockets as a transport. Using TCP/IP, it is possible to serve external clients requests (calls from other computers to this IBM i server). TCP/IP connections can be secured with SSL/TLS. Using Unix Sockets, only clients located on the same IBM i server, can access i2Rest Server.
Main Gate
This gate is used for serve requests from common clients. It is recommended to setup secured https url for this gate. All OpenAPI calls for i2Rest run_command and run_program APIs must go to this gate. API run_command requires mandatory authentication with OAuth2, while run_program APIs does not necessarily require OAuth2 authentication. You can define it in pcml file describing particular run_program API. Upon receive request without required OAuth2 authentication token, Main Gate will respond to client with 401 Unauthenticated response code. In this case client can start one of available OAuth2 flows to obtain authentication token.
Session
Each API call request that requires OAuth2 authentication will be routed to separate IBM i job, that called here as a Session. Main Gate automatically submits Session when it is issuing a new access token that includes run_command or run_program in its scope. Each access token has its own Session. If session job finishes on some reason, access token will be revoked automatically.
Session System
Commands to submit Sessions are defined in i2Rest configuration as array of Session System objects. Session System object allows you to define particular command that will be used to submit new Session. Each Session System has an unique name. You have to include 'system_<name>' in scopes while obtaining OAuth2 access token, to submit session with particular system
Setting of the submit command gives you a possibility, for example, to start a session jobs with the authority of the users who authorized the creation of the tokens
Two special Session Systems can be defined:
*LOCAL - i2Rest Server will use this system definition to submit all sessions for access tokens that does not have 'system_<name>' in its scope
*ANONYMOUS - Will be used to start anonymous sessions which will process i2Rest run_program APIs that does not have to be authenticated.
Sessions Gate
This gate is an internal endpoint that has to be available only for requests from submitted session jobs. If you plan to use only native Session Systems that will be submitted on the same IBM i where i2Rest Server is running, you can use file: endpoint in this gate settings. If you plan to serve requests from external Session Systems, it is recommended to use https: endpoint.
Session gate will listen for response messages from submitted session jobs and will route these messages to clients that called APIs on Main Gate.
Management Gate
This gate provides access to the set of i2Rest Management APIs. Access to this gate requires access token with 'management_functions' in its scope. Management Gate endpoint and Main gate endpoint must be different for the security reasons. If you plan to use i2Rest Client command to execute management functions from the terminal of the same IBM i where i2Rest Server is running, it is recommended to use file: endpoint here.
