Deploying a Technical Process as OpenAPI ReST Service

Prerequisite:

You provide of an ESB project with at least one Technical Process. 

In order to provide a Technical Process as an operation of an OpenAPI ReST Web Service, proceed as follows in the Webservice Configuration Editor:

1. Enter the desired data in the OpenAPI tab.

   

   Name, Title, and Version are mandatory field which require a value. If a method description is to be displayed in the API, please enter a description in the Description field.

2. If required, create a new node in the tree structure (corresponds to an URL part of the web service). For more information, see Editing the Web Service Configuration graphically.

3. Use Add HTTP ReST Service to create a new service of the HTTP ReST type for the desired node (of the Constant, Variable, or Remainder type). Adjust the (security) properties, if needed.

   

   Before creating an HTTP ReST service, you must set the Provide OpenAPI value on the General tab to true and uncheck the Inherit from parent node checkbox. By doing so, you specify that you use OpenAPI in the HTTP ReST service.

4. Use the Add HTTP ReST Operation context menu to create a new operation for the HTTP ReST Service or choose an existing entry from the Operations that is to be overwritten.

   

   You can assign a GET, POST, PUT, or DELETE operation once for each service or enter any operation name (the entry is case-sensitive). 

5. Drag a process from the Projects view to the desired operation via drag-and-drop in order to assign the process path.

6. Use the Output Mode drop-down to set the HTTP-Content output mode in order to display the process response.
7. If the ReST service requires query parameters, you can create them. To do so, click the Add button in the Query Parameter group box in the OpenAPI tab. When adding new parameters, you must specify a name for the parameter and additional options, such as Type, Array, and Required.
8. You can use the Request and Response tabs to create a custom request and a custom response for each method. 

Working with a Data Model

You can configure your ReST service to acquire tabular values from a data model and return tabular values. To do so, you must first create a Data Model Project containing at least one entity in the X4 Designer. Each entity must contain at least one field. For more information, see Working with Data Model Projects.

The data acquisition from a Data Model Project is possible for the POST, PUT, and DELETE methods.

Request with a Data Model

Perform the following steps in the OpenAPI tab in order to specify that  the input data for a Technical Process is to be provided in a tabular form:

1. Click on the Add button in the Request tab and enter a name into the Content-Type field. Then, click in the Data Model field, and choose the button with the three dots.
2. Select the desired data model from the Data Model drop-down in the Select Entities dialog and check the checkbox for the table whose values you would like to use. The table corresponds to the entity you have created in the Data Model Project.
   
   
   

   

   
   
   
   

Response with a Data Model

If you also want the output data of a process to be provided in a tabular form, perform the following steps in the OpenAPI tab:

1. Choose the Add button in the Status Codes section and enter the relevant HTTP status code.
2. Enter a description in the Description field.
3. Choose Add in the Contents section in order to add content to the response.
4. Choose the button with the three dots in the Data Model field.
5. Select the desired Data Model Project in the Select Entities dialog, check the checkbox for the desired table, and choose OK.
   
   
   

   

Setting the Authentication

To set a method as private, select the desired method in the Webservice Configuration Editor, and proceed as follows:

1. Uncheck the Inherit from parent node checkbox for the Realm field.
2. Enter the desired value into the Realm field, e.g. X4Realm.

Testing the ReST Service

To open the configured API in the browser, proceed as follows:

1. Call the http://localhost:8080/X4/httpstarter/ReST/[ESB_CONSTANT_VALUE]/openapi.html URL. Replace [ESB_CONSTANT_VALUE] with the name of your project.
   Alternatively, you can right-click on the method operation and choose Copy OpenAPI URL to Clipboard from the context menu. Then, insert the copied URL in the browser.

2. Expand the entry for a method under Service, and choose Try it out. 

   

   If your ReST service contains parameters, you must enter those parameters under Parameter before clicking on Execute.

   

   If your ReST service contains a Data Model Project, the data is contained in the request body. You must enter the required value before clicking on Execute.

3. Choose Execute.
   
   The result of the operation is displayed under Responses.

Testing a ReST Service with Authentication

If an authentication has been set for a ReST service, the method is marked with a lock icon on the right side. When you open the method, choose the Try it out button, enter a parameter (if required), and choose Execute. a dialog opens where you must enter your user name and password. Once you have entered your credentials, the method is executed and the response is displayed.