Hosting a REST web service

Last modified by Carlijn Kokkeler on 2023/11/03 15:22

Please note that this migration path is for the new monitoring stack only.

Below you will find a document describing the migration path to migrate your hosted REST web service on the runtime level to the latest generation runtime. For the critical aspects of the new generation compared to the current generation, please read this fundamental.

Should you have any questions, please get in touch with academy@emagiz.com.

1. Prerequisites

  • Advanced knowledge of the eMagiz platform
  • A thorough understanding of your eMagiz model

2. Key concepts

  • This migration path allows you to maintain your hosted REST web service in the 3rd generation runtime
  • Consequences of this migration are:
    • Your all-entry will be split up into separate entries
    • HTTP Settings now need to be configured under Deploy -> Architecture

3. Technical Migration Path

As part of the "Transfer Settings from Design" step in the general migration path on migrating to the 3rd generation runtime, you will see an additional option displayed below this option called "Split Combined Entries." After you have migrated your REST web service to the 3rd generation runtime, you will need to split the all-entry directly after the migration is finished.

migration-path-migration-path-emagiz-runtime-generation-3--transfer-settings-from-design-split-combined-entries-rest.png

As a result of this step, all shared resources, such as the security, will be moved to the infra flow, and the all-entry will be split into separate entries. Once this is done, you, as a user, need to execute several steps per entry before deploying your solution to any environment.

3.1. Clean up the entries

The starting point of our solution, which we are going to migrate, is the following REST web service that has two integrations linked to it.

migration-path-migration-path-emagiz-runtime-generation-3--starting-point-migration-rest-web-service-gen-3.png

migration-path-migration-path-emagiz-runtime-generation-3--all-entry-config-rest-web-service-before-migration.png

After eMagiz notifies you that the split of the all-entry was successful, you need to execute some manual actions before adding the new flows to your release. The majority of the manual changes should be performed in each split entry. After migration, each entry will contain all functional components present in the all-entry, as we cannot determine which functional components are needed to handle a specific operation. So for each entry, you need to remove all functional components irrelevant to the operation related to the entry you are currently editing. If you do not do this, the all entry is still in the release.

When opening one of the entries after migration, it looks as follows.

migration-path-migration-path-emagiz-runtime-generation-3--rest-entry-config-directly-after-migration.png

To remove all components that are not relevant anymore in this entry, please enter "Start editing" mode. In this mode, you can remove all irrelevant components from this entry. In this example, all components have something to do with the alpha operation. The result will be something like this.

migration-path-migration-path-emagiz-runtime-generation-3--rest-entry-config-after-removing-the-irrelevant-components.png

Note that you must repeat the above steps per entry created by the split action. For each entry, the irrelevant components need to be removed (which components are irrelevant is different per entry).

Please note that the Jetty component remains in every flow that is split. Main reason is that the servlet setting in that Jetty support object is required for the update of the resource path in the inbound gateway component. The resource path is now fully and only configured in that inbound gateway component. Once the resource path is updated, please remove the Jetty support object.

3.3 Alter the infra flow

To ensure that the HTTP security in the new 3rd generation runtime works as before you need to add a support object of the type "HTTP Security". In this "HTTP Security" support object you only need to define "Disabled" in the Security drop-down.

migration-path-migration-path-emagiz-runtime-generation-3--add-http-security-rest-generation-three.png

3.4 Add the split entries to a release

Now that we are finished in Create, it becomes time to deploy our changes to the Test environment. To add the new flows, particularly the new entries, to your release, you must execute the following steps.

  • Create a new release
  • Access the context menu and press "Details."
  • In the pop-up that follows search for the infra flow of the runtime you are migrating
  • Select the latest infra flow of the runtime you are migrating
    • As a result, eMagiz will automatically add the split entries to your release and will update the Release overview accordingly

After successfully completing this, the release overview should display the migrated runtime as follows.

Note that pressing the "Update flows to latest version" will not work in this scenario and the steps described above need to be executed to the letter.

migration-path-migration-path-emagiz-runtime-generation-3--release-overview-splitted-entry-rest-web-service.png

3.5 Check the Runtime Settings

One last step of the migration is to check the runtime settings of the runtime you are migrating under Deploy -> Architecture. This new functionality allows you to define the port on which the REST web service needs to be running (and optionally SSL settings when running it on-premise). You can access these settings via the context menu on the runtime level.

migration-path-migration-path-emagiz-runtime-generation-3--runtime-settings-context-menu.png

Once you have selected this option, a pop-up will appear, showing you, among others, the HTTP settings. The HTTP enabled option needs to be enabled for a REST web service, and when we look at the advanced tab, we need a reference to the port we will use here (which can be a property reference).

migration-path-migration-path-emagiz-runtime-generation-3--runtime-settings-default.png

migration-path-migration-path-emagiz-runtime-generation-3--http-settings-default-config-rest.png

If you want to learn more about the runtime settings options in general please check out this microlearning

3.6 Check your route settings

This step is only relevant when running your solution on-premise

For cloud hosted endpoints you are already used to defining a route configuration for your endpoints. With the 3rd generation runtime you also need to do this for your on-premise hosted endpoints. When configuring the route you need to take the following into account:

  • The port configured under the route must match the port defined under the Runtime settings configuration
  • The DNS left-most label has no effect and can be filled with anything
  • Make sure to link the correct container to your route

migration-path-migration-path-emagiz-runtime-generation-3--route-config-on-prem.png

3.7 Deploy the migrated REST web service to an environment

To deploy this new configuration to your environment, you need to execute step 4.4.2 (Update a subsequent runtime) of the default migration path (or step 4.4.1 should this be your first 3rd generation runtime).

4. Key takeaways

  • This migration path allows you to maintain your hosted REST web service in the 3rd generation runtime
  • Consequences of this migration are:
    • Your all-entry will be split up into separate entries
    • HTTP Settings now need to be configured under Deploy -> Architecture
Tags:
eMagiz
1.0.0