News
Abstract
There are several new features when specifying resource method information for a web service, including the ability to return data in a REST service on error HTTP status codes.
Content
You are in: IBM i Technology Updates > Welcome to IBM Integrated Web Services for i Technology Updates > Return payloads on error HTTP status codes
What is it?
There are several new features when you specify resource method information for a web service:
- The ability to return payloads when the web service is returning an error HTTP status code.
- The ability to specify HTTP headers.
- The ability to specify the identifiers to use for input and output wrapper elements.
- The ability to allow multiple input parameters not injected from an input source.
Each of the enhancements is discussed in the following sections. The sections reference the following figure:
(1) Returning payloads when the web service is returning an error HTTP status code
The Error response output parameter (1) is a new field that allows you to indicate whether a payload is to be returned when the web service implementation code returns an HTTP status code indicating an error. Previously, only the error HTTP status code was returned in the response to the client.
The field value is made up of values in a drop-down list. You can specify: *NONE, indicating that no data is to be returned; *ALL, indicating that all output parameters are to be returned; or an output parameter that has a type of character.
If an output parameter is selected, the web service implementation code may send back any payload generated by the implementation code such as HTML, JSON, or plain text by setting the output parameter field. The implementation code might need to set the content-type HTTP header to match the media type of the error data to be returned to the client. You will need to set the content-type HTTP header if any of the following conditions apply:
- If the web service resource method has the ability to produce more than one media type, such as XML and JSON.
- If the error data is in a different format than what the web service resource method produces. For example, if the resource method produces JSON but the error data is HTML.
(2) Specifying HTTP response headers
When you deploy SQL statements as REST APIs, you can specify HTTP headers that will be set in the client response via the HTTP header information (2) field. This feature has been extended to APIs based on ILE programs and service programs.
If your web service implementation code returns HTTP header information using the HTTP header array output parameter field and you specify the same HTTP headers in both places, the values are comma-separated header values instead of separate header values.
(3) Specifying identifiers to use for input and output wrapper elements
You can control the identifier (3) that is used for the input wrapper that is used for client requests and the identifier that is used for the output wrapper that is used in the response.
This is only meaningful when exchanging XML payloads. The input wrapper identifier is the root element of the request, while the output wrapper identifier is the root element of the response. Previous to this enhancement, the wrapper identifiers were based on the procedure name, and suffixed with "Input" or "Result".
(4) Specifying multiple input parameters that are not injected from an input source
You have the ability to leave multiple input parameters (4) that are not injected from an input source, in which case the integrated web services support will automatically wrap the input parameters that are not injected from an input source. Previous to this enhancement, you had to either indicate that all input parameters be wrapped or restructure your code so that those input parameters that are not injected from an input source are moved to a data structure.
Why use it?
The ability to return payloads when the web service is returning an error HTTP status code allows web service to give more detailed information about the error.
Specifying HTTP headers alleviates the need to specify HTTP headers in the web service implementation code.
Specifying the identifier that is used for the input wrapper that is used for client requests and the identifier that is used for the output wrapper that is used in the response are for those users that want to more control of the root element identifiers used when exchanging XML documents.
The ability to leave multiple input parameters that are not injected from an input source removes the need to restructure procedure parameters.
Availability
The support is enabled in the following HTTP group PTFs:
SF99713 Level 35 V7R2M0
SF99722 Level 22 V7R3M0
SF99662 Level 4 V7R4M0
[{"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"HW1A1","label":"IBM Power Systems"},"Component":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB57","label":"Power"}}]
Was this topic helpful?
Document Information
Modified date:
13 April 2020
UID
ibm16173517