REST 2.0 service binding

Use the REST 2.0 binding to access an information service through a simple HTTP interface and generate a response in either XML or JSON format. IBM® InfoSphere® Information Services Director supports GET, POST, PUT, and DELETE actions for the REST 2.0 binding.

When you attach a REST 2.0 binding, settings must be configured at the services level and operation level.

The REST 2.0 binding contains the following settings:

• Description – Description of the binding.
• Response Code Header option. Use this option to specify that service invocation errors must be returned as HTTP 200 responses.

  If this property is set, any exception thrown by the service invocation is returned as an HTTP 200 response. The custom HTTP header, X-HTTP-Status-Override, will be set in the HTTP response to the actual HTTP status code (HTTP 500, by default).

• Include this binding option. To exclude the binding from the deployment of the application that contains this information service, clear this setting.
• Operation Bindings Default Settings
  You set the default values to be used in operation bindings in the Operation Bindings Default Settings area. This provides you with the ability to set the value once at the service level for all operations. If you modify values in these fields, the operational binding configuration with the DEFAULT setting will then contain the newly specified value.

  Important: When you change a field here at the service level, the change is propagated to the DEFAULT values in the operational bindings.

  Format

  You can select either the XML, JSON, or DYNAMIC format.

  This setting specifies the required format of the REST 2.0 requests and responses. See Input argument encoding and Output argument encoding, below.

  HTTP Action

  You can select the HTTP GET, POST, PUT, or DELETE action for submitting a request to an information service provider.

  This setting specifies the HTTP method that must be used when calling the service. See HTTP Methods, below.

  Parameter Type

  You can select BODY, URLEXTENDED, URLQUERY, or MULTIPART.

  This setting specifies how service input argument values are encoded in the REST request. See Input argument encoding and Output argument encoding.

• Security

  You need to specify the security constraints for each service. The REST 2.0 binding uses these constraint definitions to properly define security constraints on the generated servlet and the corresponding service operation invocation URLs.

  If authentication is required, HTTP basic authentication is used. If confidentiality is required, HTTPS is used and must be configured in the application server.

  Requires Authentication

  Specifies if authentication is required. If you select this option, HTTP basic authentication is used for the generated servlet.

  Requires Confidentiality

  Specifies if data confidentiality is required for service invocations. If you select this option, HTTPS is required to invoke any of the service operation.

• REST 2.0 Settings in the pane for an operation.
  In the REST 2.0 Settings area, you can use default values or specify another value for this particular operation.

  Note: You set the default values at the Services level, in the Operation Bindings Default Settings area. When one of the default fields are changed at the service level, the value is automatically changed in the operational binding.

  Format

  You can select either DEFAULT, XML, JSON, or DYNAMIC format.

  HTTP Action

  You can select the DEFAULT, HTTP GET, POST, PUT, or DELETE action for submitting a request to an information service provider.

  Parameter Type

  You can select DEFAULT, BODY, URLEXTENDED, URLQUERY, or MULTIPART.

• Operation Context

  The default setting is <service-name>/<operation-name>. If you change the service name or operation name, the Operation Context value reflects the changes. This value will become a part of the URL that is used to invoke the service operation. The Operation Context value can be overwritten in the REST 2.0 Settings operation binding properties. See Calling the service by using REST, below.

  For each service operation, the combination of its operation context (default or custom) and its HTTP method must be unique across all operations of all services contained in the application. As a result, it is possible for two service operations to be invoked by using the same URL, provided that a different HTTP method is used for each of them. For example, The getCustomer operation is exposed by using the /marketing/customers/customer URL and a GET HTTP method and the deleteCustomer operation is exposed using the same /marketing/customers/customer URL and a DELETE HTTP method.

  Restriction: There is a restriction if you use the same operation context (same URL) to invoke different operations. If a given operation context is used with an HTTP PUT or DELETE method, there can be only one other operation using the same operation context and it must use the HTTP GET method. Because HTTP PUT and DELETE methods can be both tunneled through an HTTP POST by simply using the X-HTTP-Method-Override as part of the HTTP request, it might become difficult to identify the correct method to call, and there might be security issues.
• Pass-through mechanisms

  The REST 2.0 binding supports a pass-through mechanism both for input and output arguments. Using this mechanism, the service operation can receive the content of the HTTP request body “as is” and perform its own decoding logic and it can perform its own encoding logic on the result and pass it back as the content of the HTTP response body.

  Input pass through

  If you select this option, the service operation must have only one string input argument, the Parameter Type set to BODY and the associated HTTP method must be POST or PUT. In this case, the content of the HTTP request body is provided “as is” (no decoding or pass-through from the REST 2.0 binding perspective) to the service operation string input argument.

  Output pass through

  If you select this option, the service operation must return only one string value. The associated HTTP method can be GET, POST, PUT or DELETE. In this case, the content of the HTTP response body is directly set by using the service operation returned string value (no encoding, pass-through from the REST 2.0 binding point of view). The Content-Type header of the HTTP response is set according to the Format configuration:

  • Set to application/xml if the Format value is XML. The service operation is assumed to return an XML document.
  • Set to application/json if the Format value is JSON. The service operation is assumed to return an JSON string.
  • Set to application/xml or application/json if the Format value is DYNAMIC. The value of the Accept header is checked first. If application/xml and application/json are missing from the Accept header, then check the first character of the returned string: if it is a "less than" character, <, then application/xml is used, if it is an open curly brace, {, then application/json is used.

• Style Sheet File

  You can specify an XSLT style sheet for use by the REST 2 binding. Click Browse to browse your local system for a file to upload. The XSLT field is available only when the selected Operation format is XML or Default and the Service format is specified as XML. If you include an XSLT style sheet file, a processing instruction referencing this style sheet is added to the XML responses, which allows consumers of the service (for example, a Web browser) to automatically apply the style sheet on the response.

http://servername:port/wisd-rest2/<application-name>/<OperationContext>

<?xml version="1.0" encoding="UTF-8"?>
<exception xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xmlns:java="http://java.sun.com">
<errorcode>[error code]</errorcode>
<stacktrace>[The exception stack trace]</stacktrace>
<classname>[The exception class name]</classname>
<requestURI>[The URI of the original request]</requestURI>
</exception>

{"results":{"errorcode":"[error code]",
"stacktrace":"[The exception stack trace]",
"classname":"[The exception class name]",
"requestURI":"[The URI of the original request]"}}