Defining HTTP-to-JSON mapping

The next step in modeling your API is to map HTTP headers, path parameters, and query parameters with fields in the JSON schema of a z/OS® Connect service. The JSON schema is the metadata that is used to communicate with the service.

Before you begin

If your API project is not yet open in the API editor, in the Project Explorer view, open the package.xml file located in your API project.

Procedure

  1. In the API editor, click Mapping on a method to map fields in the JSON schema of the service, and then select Open Request mapping (HTTP request) or Open Response mapping (HTTP response).
    The mapping editor opens.
  2. Create HTTP headers and query parameters. Each HTTP method can have its own HTTP headers and query parameters.
    • To create an HTTP header for the request or response messages, right-click HTTP Headers > Add HTTP Header.
    • To create a query parameter, right-click Query Parameters > Add Query Parameter.
      The value of a query parameter is passed in by the HTTP client as a key-value pair, connected by an ampersand (&), in the query string at the end of the URL. The following example shows two query parameters, min and max, that are used to pass in a minimum value and a maximum value: 
      /patients?min=5&max=20
    • To customize the data type for a URI path parameter for this method, right-click the path parameter and select Edit Path Parameter.
    Note:
    • The data type for HTTP headers, query parameters, and path parameters can be string, integer, boolean, number, or array. When the data type is set to array, you must specify the array data type and array format. For more information, see Defining and mapping headers, query parameters, or path parameters.
    • If there are multiple HTTP headers, query parameters, or path parameters, to enhance readability, you can reorder them by right-clicking an entry and selecting the appropriate menu option to move it up or down. The same order is reflected in the generated Swagger document but does not affect the run time. Headers or query parameters can be passed in from the API call in any order. Path parameters, however, are defined in the API editor and their values must be passed in the defined sequence.
  3. Map HTTP headers, query parameters, and path parameters with the service JSON schema by dragging the header or parameter to a field in the JSON schema.
    This is known as the Move transform. For more information about the mapping rules, see Request and response mapping rules.
  4. Assign any static values or remove any unnecessary field from the service JSON schema.
    Mapping actions Description
    Assign Assigns a static value to a field in the service JSON schema for the HTTP request or HTTP response.
    Remove Hides the value from the HTTP request or HTTP response.
    Task Allows adding a description and detailed documentation for communication purposes.
    Note: Path and query parameters inherit the minimum, maximum, minLength, maxLength, exclusiveMinimum, and exclusiveMaximum properties of the service field to which they are mapped.
    To use the Assign mapping action:
    1. Right-click the field to be assigned and select Add Assign transform.
    2. Select the Assign box to open the Properties view.
    3. In the General tab of the Properties view, type the required value into the Value field.
    4. Optionally, add a description in the Documentation tab.
    Tip: Unmapped fields in the request JSON schema remain unchanged and get their values from the body of the HTTP request. If no value is provided from the JSON payload, the default value that is specified in the service interface editor during service definition is used. z/OS Connect will ensure that there is always a JSON object for service interface defaults to be applied to. Where the received HTTP request has no body, z/OS Connect will still apply default values set for fields in the service interface.

Example

In the following example, a healthcare service provider is developing an API to allow their patients to look up their registration information based on their patient ID.

In the mapping editor, an API developer created and mapped the following HTTP header, path parameter, and query parameters for the GET HTTP method:
HTTP header: X_TrackingID
Enables the service caller to provide the routing information (CA_ROUTING_CODE) for a patient with the HTTP header variable called X_TrackingID.
Path parameter: patID
Enables the service caller to set the value for CA_PATIENT_ID as the provided patID value.
Query parameter: userID
Enables the service caller to set the value for CA_USERID as the provided userID value.
Query parameter: zipCode
Enables the service caller to set the value for CA_POST_CODE as the provided zipCode value.

An example mapping configuration for the HTTP request and request JSON schema.

The screenshot shows an example mapping configuration for the HTTP request and request JSON schema.