REST request / response
16.1.2. Flow Engine interaction with REST API

The following diagram gives a schematic view of how the flow engine processes flow steps and how the flow engine interacts with the REST API.

The example below illustrates the fact, that the flow steps configured in Airlock IAM do not correspond one-to-one to REST requests and responses. Each REST request calls exactly one interactive step method. If the REST request is successful one or more init methods of the following steps will be processed automatically until the next interactive step is encountered. Only at this point, the REST response is sent back to the client.

  • Thus the response to a request may be sent back by either of the following:
  • by the method of the step that processed the request.
  • by a different method of the step that processed a request.
  • by the init method of a subsequent step in the flow.

This diagram reuses the example flow sequence presented in 17.2.3. User self-registration REST API:

118883201.png

The schematic above illustrates a sequence of flow steps and highlights some of the options that the designer of a flow may consider.

  • Of particular interest are the following aspects:
  • 1.
    The flow is started by a REST call to the registration/data endpoint.
  • 2.
    The flow state machine initializes itself to handle this particular self-registration flow.
  • 3.
    The flow is started with the INIT method of the registration data step.
  • 4.
    Control is handed back to the Flow State Machine and since the REST request is for the registration/data endpoint the registration data method is immediately called. The method processes the attributes. In this example, the validation is not successful. The failure including the reason for the failure is reported back to the User Client as a REST response. In the REST response, USER_DATA_REGISTRATION_REQUIRED is indicated as the only next step possible at this point in the flow.
  • 5.
    The client sends another REST Request to the registration/data endpoint and this time supplies the full/correct set of attributes. The Flow State Machine calls the method with the attributes from the REST request. The method validates successfully and returns a successful response. In the REST response, the method returns USER_DATA_REGISTRATION_POSSIBLE to indicate that both registration/data and continue are possible as next request.
  • 6.
    The client sends a REST request to the registration/continue endpoint. The Flow State Machine supplies the information to the continue method of the registration data step. This method reports success back to the flow state machine.
  • 7.
    The Flow State Machine immediately calls the INIT endpoint of the generate username step. This step generates a username and returns a successful response to the Flow State Machine.
  • 8.
    The Flow State Machine immediately calls the INIT method of the email otp check step. The INIT method generates an email message with an OTP code to be sent to the email address supplied during the registration data step. It then creates a successful response to the User Client and indicates that email otp check is the only next step possible in the flow. 
  • 9.
    The User Client sends a REST request to the verification/email/otp/check endpoint containing the OTP code. The Flow State Machine calls the email otp check method with the OTP code as an attribute. The method verifies the OTP code and verification fails. A REST response is sent to the User Client indicating a failure and the failure reason. As a next step, the email otp check method is offered.
  • 10.
    The client creates a second REST request to the verification/email/otp/check endpoint containing the correct OTP code. The Flow State Machine calls the email otp check method with the OTP code as an attribute. The method verifies the OTP code and verification succeeds. This triggers the flow state machine to automatically continue with the next step.
  • 11.
    The INIT method of the registration data step is for an interactive step. It creates a REST response for the success of the previous step and uses USER_DATA_REGISTRATION_REQUIRED to demand a password to be supplied. 
  • 12.
    The client creates a REST request to registration/data to supply a password. The password method processes the supplied password and sends back a REST response indicating success. As a next step, a call to continue is required.
  • 13.
    The client creates a REST request for the registration/continue endpoint. The flow state machine calls the continue method registration data step. This method reports success to the flow state machine.
  • 14.
    The flow state machine immediately calls the INIT method of the user persisting step. The user persisting step writes the user information to the data store, creates a REST response to the client indicating success, and reports a success back to the flow state machine. 
  • 15.
    The flow state machine terminates the flow.