How to use the API editor

IBM® z/OS® Connect zosConnect-2.0 provides an Eclipse-based API editor for you to design and create REST APIs for JSON services that are deployed on the z/OS Connect Server.

zosConnect-2.0 Applies to zosConnect-2.0.

The editor is GUI-based, so you can use the common keyboard and mouse-click actions for your API design needs, such as:

  • Drag-and-drop to map incoming data from the HTTP headers, path parameter, or query parameters to fields in the service.
  • Right-click to access menus for actions applicable to the selected elements, such as adding or editing a query parameter, assigning a value to a field, or undo a transform action.
  • Control or Shift keys to select multiple fields.

For tutorials about how to create a REST/JSON service from various applications, and how to create a REST API to act on the service, see Quick start scenarios with IBM z/OS Connect zosConnect-2.0

Tip: To open the API editor for an existing API project, double-click the package.xml file in your project folder in the Project Explorer view.
Assume that you have the following API project to allow your users to add a work contact.
The API name, base path, and path with the path parameter and query parameters are defined and ready to do the mapping for the POST method.
In this example, Last name is the key that uniquely identifies the contact, and users complete the given name, extension, and postal code for the given surname.

You have the API name, base path, and path defined. Click Mapping to start mapping the incoming data from the HTTP POST request to fields in the service.

The API name, base path, and path with the path parameter and query parameters are defined and ready to do the mapping for the POST method.

You have the API name, base path, and path defined. You are now ready to click Mapping to start mapping incoming data from the HTTP POST request to fields in the service.
Opening the mapping editor for an existing API.
Tip: You can open the request or response-mapping editor for an existing API project directly by double-clicking the request.map or response.map file in the /api folder of your project in the Project Explorer view.
As you open the request mapping, you see the HTTP request on one side and the fields in the service on the other. As an API developer, your primary interest is to map the incoming information from the HTTP request, typically in the header or in a parameter from the left, to appropriate fields in the service on the right.
The mapping editor, with HTTP request on the left and service JSON schema on the right
If you open the response mapping, you see fields in the service on the left and the HTTP response on the right. As an API developer, your primary interest is to determine what information from the service to send back to the body in the HTTP response. You can also remove some fields from the response and send back only needed information.
For the response mapping, the service fields are on the left, and the HTTP response is on the right.

Transform actions

The goal of the mapping editor is to let you more easily design and test a light-weight REST API in a graphical user interface. The goal is achieved mainly through the data transform actions, including:
  • Move: Move data coming from the HTTP header, path parameter, or query parameters to appropriate fields in the service.
  • Remove: Hide a field in the service. This action is often used in the response mapping so unnecessary fields are not available to the API for the HTTP response.
  • Assign: Assigns a static value to a field in the service.
To move data from the HTTP request to appropriate fields in the service, move your mouse over the element in the HTTP request and simply drag and drop. Here, we’re getting the last name, first name, extension, and zipcode from the HTTP header, and moving them into the appropriate fields in the service.
Mapping values from path parameter and queries parameters to appropriate fields in the service.
You can also easily add an HTTP header or a query parameter through the right-click context menu:
The context menu when you right-click HTTP Headers.
For the work contact to be added, the IBM Z application has defined ADD as the command for adding a record, so we right-click the IN_COMMAND field in the service and select Add Assign transform.
Assigning a value to a field
You can then specify the value to assign for this field in the Properties tab. For this example, specify the value of ADD.
The mapping editor, with HTTP request on the left and service JSON schema on the right
Assigning a value of ADD to a field

If you make a mistake, you can undo or delete your transform action by right-clicking the action and select Delete from the menu.

Multi-select

To select multiple fields for the same action, you can:
  • Select a block of fields by selecting the first field, holding down the Shift key, and by using the Up or Down arrow to extend the selection.
  • Select a block of fields by drawing a box around the fields with your mouse.
  • Select multiple fields that are not next to one another by selecting the first field, holding down the Ctrl key, and clicking the other fields that you want to select.
The following example shows the use of the mouse to draw a box around the block of fields. As soon as you release the mouse button, the fields in the box will be selected for your transform action.
Using the mouse to draw a box around the fields you want to select You can also select a block of fields by holding down the Shift key and pressing the up or down button.
The following example shows the use of the Ctrl key to select multiple fields to remove from the HTTP response that are not next to each other. In this example, the only information that is returned is the output message (OUT_MESSAGE) that indicates whether the operation was successful or not for the specific last name (OUT_LAST_NAME). We don’t want to echo back the other information.
Selecting multiple fields to remove

Reimporting changed services

If a service is modified after your API is created, don’t worry! You can re-import the changed service definitions into the project, and the impact of the changes is analyzed and reported, with mapping issues recorded in Eclipse’s Problems view. If the impact on the existing mappings is as expected, you can click OK to re-import the services, and resolve any remaining issues that are reported in the Problems view.
Mapping issues due to a changed service is reported in Eclipse’s Problems view.