REST Service 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
Resource The name of the resource.
Resource Service Path Specify the path to the Service Resource.

Define parameters in the resource service path by enclosing each parameter in { } brackets. For example, to define the path parameter isbn for a book resource, specify the resource path as follows:

/book/{isbn}

In this example, the client would invoke this service using the URL http:/<host>:<port>/book/<isbn>.

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.

If an application contains multiple REST bindings, ensure that the location of the path parameters is unique for each REST binding.

An example is that of one REST binding using the /book/{isbn} path and another REST binding is using the /book/{authorid} path. Since {isbn} and {authorid} are defined at the same location in the URI , one of these services will not function as expected.

In addition to path parameters, the path in a REST binding can also contain query parameters. For example,

/resource/path/{pathparam}? query={queryparam} or /resource/path/{pathparam}?{ queryparam}

HTTP Connector Name The name of the HTTP Connector.
Tip: Click on the HTTP Connector Name field to display details about the HTTP Connector resource.

By default, a new HTTP Connector Shared Resource is created when you create a new REST Service binding. Change the field value type to Module Property to specify a module property that has been defined as an HTTP Connector Shared Resource.

Response Client Format The type of response message format. The supported response message formats are:
  • JSON
  • XML
Enforce BW Service Response Select the check box to set the response preference to BW Service Response.

By default, the check box is not selected, and the response preference is set to the Accept Header response.

For more information about the REST Service responses based on the Accept Header settings, see Accept Header Responses topic .

Start Job on Input Exception Select the check box to start the job when there is a wrong or erroneous input.
Note: Imported projects display the Authenticate check box under the Binding section if the check box was selected in a previous version TIBCO ActiveMatrix BusinessWorks™ 6.x. Authentication also remains enabled on the REST Service Binding if you do not clear the check box. Clearing the Authenticate check box causes a warning message to be displayed prompting you for confirmation. Clicking OK causes the Authenticate check box to no longer display and removes authentication from REST Service Binding . Click Cancel to retain the Authenticate check box, and to continue enforcing authentication on the binding.

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

Operations

This section shows the following details.

Field Description
Name The name of the HTTP method used, for example, POST, GET, PUT, PATCH, and DELETE.
Nickname The specified name of the service, for example, getBooks.

Operation Details

This section has the following tabs.

Summary tab
Field Description
Summary The summary of the REST resource.
HTTP Method Displays the HTTP Method specified in the Operations section. These are the available HTTP methods:
  • POST
  • GET
  • PUT
  • DELETE
  • PATCH
Notes Additional information about REST resource.
Request tab
Field Description
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 Supported formats for REST service request are:
  • JSON
  • XML
  • Text
JSON Definition Style Select one of the following options:
  • Single Element: Returns an element of corresponding data type, or a single schema element when a schema is selected.
  • Anonymous Array: Returns a JSON array without the parent element, where the root element has exactly one child of the type Array.
  • JSON with Root: Includes the root element in the input JSON string.
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.

  • 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 toggleed to Yes and No.

  • Required

This field can be toggleed to Yes and No.

Response tab
Field Description
Use HTTP Headers Selecting this check box includes the response headers element. Response headers are not commonly used, so select this check box only when you need to include response headers.

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

Use Custom Status Line You can specify a custom status line (status code and reason phrase) to the outgoing message. The codes used must be defined in the configuration under the Response Status tab.
Response with Status Code Only The operation returns a status code as response, when this check box is selected. Message body is not required. For example, using a POST operation returns a 201 status code which means "Created" and responds with the resource URL.
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
JSON Definition Style Select one of the following options:
  • Single Element: Returns an element of corresponding data type, or a single schema element when a schema is selected.
  • Anonymous Array: Returns a JSON array without the parent element, where the root element has exactly one child of the type Array.
  • JSON with Root: Includes the root element in the input JSON string.
Resource Schema Displays the schema selected. This option is not available when the Use Custom Status Line and Response with Status Code Only check boxes are selected. 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.

  • 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 toggleed to Yes and No.

  • Required

This field can be toggleed to Yes and No.

Response Status tab
Column Name 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.

Path Parameters

This section shows the following details.

Parameter Name Type
Parameter name of the operation used The parameter type. It can be any one of the following:
  • String
  • Integer
  • Boolean
  • Long
  • Float
  • Double
  • Byte
  • Binary
  • Date
  • DateTime
  • Password

Advanced Configuration

This section has the following field:

Field Literal Value/ Module Property Description
Blocking Queue Size Yes This field sets the number of threads to be created for a REST service. It gives you control over the number of threads that are created for the REST service. By default, it is set to a large integer value.

Policies

To associate a new or existing policy with the REST binding, click Policies node under the RestService 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 binding can support the Basic Authentication policy. For more information, see "Enforcing Basic Authentication".
Description A description of the policy.