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 still passes successfully.

If an application contains multiple REST bindings, make sure 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 do 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: To display details about the HTTP Connector resource, click on the HTTP Connector Name field.

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 checkbox to set the response preference to BW Service Response.

By default, the checkbox 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 the Accept Header Responses topic.

Start Job on Input Exception Select the checkbox to start the job when there is a wrong or erroneous input.
Apply Policy to Subpaths Select the checkbox to apply a policy to the sub-paths of a REST service.
When this checkbox is selected for a parent Resource Service Path configured with policy, the policy is applied to the child paths at runtime. If in case we do not wish to apply the policy to all the sub-paths but for selective paths, then do not select this checkbox and add the policy for the required service paths.

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 checkbox to set NULL values instead of empty values in JSON. That is, use NULL values instead of square brackets ([]).

By default, the checkbox is clear.

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

By default, the checkbox 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 Element
  • String
  • Integer
  • Boolean
  • Form Data - Tag/Value (application/x-www-form-urlencoded)
  • Form Data - Multipart (application/form-data)
Query and Header Parameters You can perform the following operations:
  • Add Query Parameter
  • Add Header Parameter
  • Remove Parameter
  • Scroll Up
  • Scroll Down

This pane has the following 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 toggled to Yes and No.

  • Required

This field can be toggled to Yes and No.

  • Description

    You can edit this field to provide additional details by clicking on the parameter added. For newly created services, this field's details reflect in the Swagger file generated within TIBCO BusinessWorks Container Edition. For existing Swagger files with this field, you must create a new service using the Swagger file.

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

When you select this checkbox, 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 checkbox 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 checkbox to set empty values instead of NULL values in JSON. That is, use square brackets ([]) instead of NULL.

By default, the checkbox is clear.

Format Supported formats for REST service request are:
  • JSON
  • XML
  • Text
  • Binary - This checkbox is visible only for Swagger 3.0 REST services.
Note: When you select the Binary checkbox all other checkboxes are disabled and the JSON Definition Style option is not visible. Instead, the Media Types field is displayed.
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.
Media Types

This field is enabled only when the Binary checkbox is selected.

Select one of the following options :

application/octet-stream
application/pdf
image/png
image/jpeg

To dynamically set a binary media type other than the available options , do the following:

Ensure that you have Media Type as application/octet-stream.
Select the Use HTTP Headers checkbox and then pass Media Type value in the Content-Type response header. This media type is not updated in the Swagger file but is set at run time.
Resource Schema

Displays the schema selected. This option is not available when the Use Custom Status Line and Response with Status Code Only checkboxes are selected. The following options are available:

  • binary: This option is available only when you select the Binary checkbox.

  • base64: This option is available only when you select the Binary checkbox.

  • 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 that 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 checkbox is selected.

You can perform following operations:

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

This pane has the following 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 toggled to Yes and No.

  • Required

This field can be toggled to Yes and No.

  • Description

    You can edit this field to provide additional details by clicking on the parameter added. For newly created services, this field's details reflect in the Swagger file generated within TIBCO BusinessWorks Container Edition. For existing Swagger files with this field, you must create a new service using the Swagger file.

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 checkbox is selected in the Response tab.
Restriction: If you select the Response Format as Binary, do not add any status code.
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 Description Repeating
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

You can edit this field to provide additional details by clicking on the parameter added. For newly created services, this field's details reflect in the Swagger file generated within TIBCO BusinessWorks Container Edition. For existing Swagger files with this field, you must create a new service using the Swagger file.

 

This field can be toggled to True or False.

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.