REST Reference Binding

REST Binding provides external connectivity for REST over HTTP. You can specify custom HTTP headers and parameters using REST binding. It supports POST, GET, PUT, PATCH, and DELETE HTTP methods. It also supports JSON, XML, and plain text message types.

Binding

This section has the following fields.

Field Description
Implementation Resource

or

Resource Service Path

The Swagger specification in the project that defines the REST endpoint. This field is visible only when the reference is defined by a Swagger specification, otherwise this field is replaced by the Resource Service Path, which is the path to the resource.
Resource Service Path Resource path of the REST Resource to invoke.
Note: Path parameters that are not immediately enclosed in forward slashes are supported. For example, the parameter authorName('{isbn}') in the resource service path /book/authorName('{isbn}')/ is not directly contained by forward slashes, but will still successfully pass.
HTTP Client The name of the HTTP Client.
Tip: Click on the HTTP Client Name field to display details about the HTTP Connector resource.
Request Client Format

The type of request message format.

The two available reply message format options are: JSON or XML.

Applies to all operations unless overridden at the operation level.

Response Client Format The type of reply message format.

The two available reply message format options are: JSON or XML.

Applies to all operations unless overridden at the operation level.

Path Parameters If Path parameters are defined in the REST service that the REST Reference is calling, they appear in the Path Parameters table. However, you cannot modify the Path parameters since the REST Reference must adhere to the parameters defined by the service.
Note:

To enforce authentication on the REST Reference Binding, use the authorization header or associate the binding with a Basic Credential Mapping policy. For more information, see "Enforcing Basic Credential Mapping"

Summary tab

This tab shows the following details.

Field Description
Summary A brief description of the operation.
HTTP Method A unique identifier for the operation that identifies the operation in the entire API. By default, it is set to <HTTP-Method>-<resource_name>.
Notes A field that can be used to describe the operation. Any text that is entered in the Notes field appears in the Swagger file.

Request tab

This tab shows the following details.

Field Description
Use Empty Values for Null Select the check box to set empty values instead of NULL values in JSON. i.e use [] brackets instead of NULL.

By default, the check box is clear.

Format Supported formats for REST service request are:
  • JSON
  • XML
  • Text
Request Entity Processing
This field has two values:
  • BUFFERED: the request entity is buffered in memory to determine the content length that is sent as a Content-Length header in the request.
  • CHUNKED: the entity is sent as chunked encoded (no Content- Length is specified, entity is streamed). The Transfer-Encoding header is set to Chunked.

The default value is Chunked.

JSON Definition Style Specifies whether the request item is a Single Element or an Anonymous Array.
Request Data type of the Payload. It can be one of the following:
  • XSD Elelment...
  • String
  • Integer
  • Boolean
  • Form Data - Tag/Value (application/x-www-form-urlencoded)
  • Form Data - Multipart (application/form-data)
Query and Header Parameters The user can perform following operations:
  • Add Query Parameter
  • Add Header Parameter
  • Remove Parameter
  • Scroll Up
  • Scroll Down

This pane has 4 columns:

  • Parameter Name
    Name of the parameter. Users can edit the parameter name by clicking on the parameter added.
    Note: Do not use a space in the HTTP header name. If you do, the following error is displayed: Bad message- 400 - Illegal character.
  • Type

    Data type of the parameter. It can be:

    • String
    • Integer
    • Long
    • Float
    • Double
    • Boolean
    • Byte
    • Binary
    • Date
    • Date Time
    • Password
  • Repeating

This field can be toggled to Yes and No.

  • Required

This field can be toggled to Yes and No.

Response tab

This tab shows the following details.

Field Description
Use HTTP Headers Select this check box only if you require a service to send back a custom header, or value or if you need to see the response headers.

This check box is selected by default if custom headers are used.

When you select this check box, you can add custom HTTP fault headers defined in the Response Status tab.

Use Null for Empty values Select the check box to set NULL values instead of empty values in JSON. i.e use NULL values instead of [] brackets.

By default, the check box is clear.

Ignore Additional JSON Fields Select this check box to ignore additional fields that are generated due to changes in the external payload when processing the schema.

By default, the check box is clear.

Format Response format requested by the client , can be JSON, XML or Text. The service must support the formats that the client requests for this operation.
JSON Definition Style Specifies whether the request item is a Single Element or an Anonymous Array.
Resource Schema These are the available options:
  • String
  • Integer
  • Boolean
  • XSD element: Selecting this option to either select the XSD schema element available under the Schemas folder of your project or a create new XML schema resource. Click Create New Schema to a create new XML schema resource using the Simplified Schema Editor wizard.
    Note: Ensure the schema resource you select does not contain cyclic dependencies on other schemas , or a type that has two child members with the same local name, but different namespaces.
Header Parameters This field is enabled only when Use HTTP Headers check box is selected.

The user can perform following operations:

  • Add Header Parameter
  • Remove Parameter
  • Scroll Up
  • Scroll Down

This pane has 4 columns:

  • Parameter Name

    Name of the parameter. Users can edit the parameter name by clicking on the parameter added.

    Note: Do not use a space in the HTTP header name. If you do, the following error is displayed:Bad message- 400 - Illegal character.
  • Type

    Data type of the parameter. It can be:

    • String
    • Integer
    • Long
    • Float
    • Double
    • Boolean
    • Byte
    • Binary
    • Date
    • Date Time
    • Password
  • Repeating

This field can be toggled to Yes and No.

  • Required

This field can be toggled to Yes and No.

Response Status tab

This tab shows the following details.

Field Description
Code These are unique numbers. Click on the error code to customize it.
Note: Use custom status code 200 only when the response is not defined, that is, when the Response with status code only check box is selected in the Response tab.
Type Data type of the error code. Following types are supported:
  • XSD Element...

    Select this option to either select the XSD schema element available under the Schemas folder of your project or create a new XML schema resource.

  • String
  • Integer
  • Boolean

The default type is String.

Reason Phrase Description of the error code. Click on the value to customize the description.

Policies

To associate a new or existing policy with the REST Binding, click Policies node under the Rest Reference tree, then click Add Policy to create a new policy. To edit an existing policy details, click the policy name and edit any of the following fields.

Field Description
Policy Name The name of the policy.
Policy Type The type of policy associated with the binding. The REST Reference Binding supports the Basic Credential Mapping policy. For more information, see "Enforcing Basic Credential Mapping".
Description A description of the policy.

Enabling JSON Payload Logging

To enable raw JSON payload logging for both Inbound and Outbound of the Invoke activity for REST binding in debug logging, add the following VM arguments:

  • -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
  • -Dorg.apache.commons.logging.simplelog.showdatetime=true
  • -Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
  • -Dorg.apache.commons.logging.simplelog.log.org.apache.http.wire=DEBUG