You can define multiple HTTP response codes to allow you to quickly determine the results
of a REST API operation. Defining multiple response codes also allows you to efficiently detect and
handle errors with your REST API. You can define custom HTTP headers and customize the HTTP response
body to relay the appropriate information from your REST API.
Before you begin
If your API project is not yet open in the IBM® z/OS® Connect
API editor, in the
Project Explorer view, open the package.xml file located
in your API project.
Restriction:
To successfully create and deploy an API utilizing multiple response codes, ensure that you are
using the minimum required version of IBM z/OS Connect, version 3.0.16.
Procedure
-
In the API editor, click
for the method you want to add a response
to.
Response details for your API method is shown. A default response code,
200
, is preconfigured for each API method.
-
Under
Responses
, click the Add Response button () to define a new HTTP response
code.
The Add Response window opens.
-
In the Response code field of the Add Response window, specify a HTTP
response code. Select a response code using the drop-down list, or alternatively specify your own
response code in the numeric range of 100 to 599 by typing into the text field.
- Use the Description field to specify the purpose of the response
code.
- Define the rules that are used to determine when this response code is issued. A rule is
composed of (from left to right) a name, a service response field, a comparison operator, and a
comparison value.
- In the Rule name field, specify a short name that identifies
the rule.
- In the service field drop down box, select a service response
field to compare against.
Restriction: Array types cannot be used for a service field.
- In the comparison operator drop down box, select an operator to
compare the service field value against the comparison
value.
Comparison operators will change according to the datatype specified in the
service field box.
- In the comparison value field, specify a value to be compared
with the corresponding service field value.
The structure of rules used for multiple response codes typically mimics the conventions used for
performing programmatic comparisons in Java. To see a demonstration of rules used for multiple
response codes, see the IMS API example
Define contacts API response codes.
Restriction: Array type service fields cannot be used for rule definition.
- When you are finished specifying rules for your response, click
OK.
Important:
- To later edit the rules for a given response, return to the Add Response window by clicking
.
- To delete a rule, click the Delete rule button () for that
rule.
- Rule errors will prevent you from saving a response code. To resolve errors within the Add
Response window, mouse over any error indicators to be prompted with the solution.
-
(Optional): Define unique service response JSON mapping for when this response code is issued.
- To configure unique response mapping for an API operation, click
for the response you want to edit.
- To delete a unique response mapping, and revert to the default response mapping, click
for the response you want to delete.
Specifying a unique service response mapping allows you to return the appropriate
information for a given response. For more information about response field mapping, see
Defining HTTP-to-JSON mapping.
Important:
If you do not specify a unique service response mapping, the default 1-to-1 mapping between the
service and API response fields will be used.
- Specify the order in which response codes are evaluated. Click the up () and down () arrow buttons for each response to increase or decrease the
precedence of evaluation for each response code. The response with the lowest precedence is marked
as the default response code.
Important:
Responses are interpreted sequentially, in the order of highest precedence (top) to the lowest
precedence (bottom). During rule evaluation, all service response fields are tested against the
rules defined for the API method. After rule evaluation, API response field mapping is
performed.
During an API operation, if none of the rule sets for each response evaluates to true, the
default response code is issued. The default response is marked with a check mark next to the
response code.
- Once you are finished, click
(Crtl-S) to save
changes made to your API methods.
Results
You have created multiple response codes for an API operation that are issued according to
their specified rule evaluation.
What to do next
Deploy an API.