REST Binding

REST Binding provides external connectivity for REST over HTTP. You can specify custom HTTP headers and parameters using REST binding. It supports GET, PUT, POST, 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 of the Service Resource.
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.
Request Client Format The type of request message format.

The two available request message type options are: Body and Form.

  • Body: Provides two request body format option: JSON and XML. Both or any one of these options can be used.
  • Form: This option can be used to inject the parameters of a Web form into a RESTful web service.
Reply Client Format The type of reply message format.

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

Operations

This section shows the following details.

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

Operation Details

This section shows the following details.

Field Description
Summary This tab has the following available options:
  • 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
Request Specifies the resource created, using the POST method.
Note: Request and Response depend on the method selected.
Response This tab has the following available options:
  • Use HTTP Headers: Selecting this check box includes the REST Web service application (or client) within the HTTP headers and body of a request, all of the parameters, context, and data required by the server-side component to generate a response.
  • 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.
  • 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.
Response Status Specifies the response code for the operation and the code message. For example, code 201 means Created or code 503 means Service Unavailable.

You can also add your own custom code and reason phrase.

Parameters

This section shows the following details.

Parameter Name Type Required
Parameter name of the operation used The parameter type. It can be any one of the following:
  • String
  • Integer
  • Boolean
Whether this parameter is required. The available options are Yes or No.

Working with Path and Query Parameters

TIBCO Businessworks Container Edition REST binding supports the use of path parameters for the resource service path (for example, /books/{isbn} instead of /books} in the REST service. The user must specify every parameter by enclosing it in brackets { }. For example, /book/{isbn} specifies the user can have isbn as a parameter. The client invokes this service using the URL http:/<host>:<port>/book/<isbn> where <isbn> is an actual value. Using the path parameters combined with static URL, for example, /book/{isbn}/events, is also supported.

Important: The Query and Path parameter names should not be same as the Form parameters name. For example, if Form parameter contains name as one of its parameter, the following path and query parameters are not allowed and throws an exception:

/resource/{name}

/resource?name={name}

All the parameters defined in the resource service path are made available to the user as an Input for every operation. Refer to Support for Path and Query Parameters. See the following image for the /book/{isbn} ) example to see the Input for the GET operation.



About Swagger UI

Using the Swagger UI you can visualize RESTful services. It specifies the format (URL, method, and representation) to describe REST the web services.

Note: Authentication support has been added to the REST binding. Hence, the Swagger UI displays Basic Auth Username and Password fields, regardless of whether the Authenticate check box is selected or not selected in REST binding.

Partial Response in REST

Using the Partial Response feature in REST, you can retrieve only the data you need, instead of bulk data as a response. You can also request only those fields that are required as part of the response.

For example, in the Swagger UI to select the immediate children nodes of an object, specify the required field names separated by comma such as ISBN, author, bookName, and so on.

The partial response feature uses a fields query parameter.

Note: The fields keyword is reserved to be used internally by BusinessWorks Container Edition. Adding the fields keyword as a query parameter automatically triggers support for partial responses.

Partial responses do not support selecting particular objects from an array. For example, using the fields keyword for /books/isbn, the isbn's of all the books are returned.

Format: The values of the fields keyword can be a comma separated value of fields of the response message. Fields can be specified directly, for example, using isbn or hierarchy /book/isbn.