We Have Moved

The IBM Application Gateway has a new home - docs.verify.ibm.com/gateway

The documentation on this site will no longer be maintained after v21.02, please update your bookmarks.

Defining Custom Responses

The IBM Application Gateway (IAG) under certain conditions will return server generated responses. These conditions include scenarios such as error conditions or server generated operations.

By default, IAG includes a set of unbranded responses which will be served. A copy of the default responses are can be retrieved from the pages directory of the IAG Resources repository.

Replacing the default Response Pages

Server generated responses can be customized by providing a set of response templates in the directory structure expected by IAG. The content can either be provided as a zip archive or a directory which is bind mounted into the IAG container.

For example, to replace the default error responses with the content of an archive 'errorPages.zip' which is mounted in the container at '/var/iag/config/errorPages.zip':

server:
  error_pages:
    content: "@errorPages.zip"
    type:    zip

See also: YAML Reference for error_pages

For example, to replace the default management responses with the content of the directory 'myMgmtPages' which is mounted in the container at '/var/iag/config/myMgmtPages':

server:
  management_pages:
    content: myMgmtPages
    type:    path

See also: YAML Reference for management_pages

Note that if custom responses are provided, IAG will not use any responses from the default set of responses. That is, if a custom set of responses is provided it is expected to include all possible responses you wish for IAG to serve. For this reason, the strategy recommended when customising responses is to begin with the archive of default responses and make additions/omissions as required.

Directory Structure and Naming Convention for Management and Error Responses

The template content for Management and Error responses is expected in a specific directory structure adhering to the following name convention.

Note that the token '<response_code>' is optional for both management and error pages.

Management Pages

'<language_code>/<page_name>.<response_code>.<mime_type>'

Example

./C/help.html
./C/login_success.html
./C/logout.html
./C/oidc_fragment.html
./C/ratelimit.html
./C/redirect.html
./C/temp_cache_response.html
./cs/help.html
./cs/login_success.html
...

Error Pages

'<language_code>/<error_code>.<response_code>.<mime_type>'

Example

./C/38cf0420.html
./C/38cf0421.html
./C/38cf0427.html
./C/38cf0428.html
./C/38cf04c6.html
./C/38cf04d7.html
./C/38cf08cc.html
./C/default.400.html
./cs/38cf0420.html
./cs/38cf0421.html
...

Controlling Language Support with 'language_code'

The default set of responses are provided in 14 different languages. When creating the directory structure, directories for languages you do not wish to serve can be omitted.

IAG will select the language for the response using the following logic:

1. If a client indicates a particular language and a response exists for that language, it will be served.
2. If a client indicates a particular language and a response does not exist for that language, IAG will select a response using the container language (set via the 'LANG' environment variable)

The complete list of languages supported by IAG and their corresponding 'language_code' values are listed below.

Example

Consider a scenario where your application is being deployed for Canadian users and you want to only ever return English or French server generated responses.

To only ever return responses in English or French with all other languages falling back to English:

1. Include only the 'C' and 'fr' directories in the directory structures for your management and error responses
2. Run the container with 'LANG=C' to indicate that English is the default language

Customising HTTP Status Codes with 'response_code'

The HTTP status code returned for management and error responses can be customised on a per-response template basis. This token of the filename in the naming conventions is optional, if a 'response_code' is not explicitly indicated, the default value will be used.

Management Responses

The default HTTP status code for management responses is 200.

Error Responses

The default HTTP status codes for error responses vary based on the type of error. The default status codes for the standard set of error responses are:

Customising Responses for Different Types of Clients with 'mime_type'

IAG can serve different responses based on the MIME sub-type found in the request.

For example:

1. A web browser which presents an 'accept: text/html' header will receive the 'html' response
2. An API client presenting 'accept: application/json' will receive a 'json' response - provided that a 'json' response template exists in the directory structure.

IAG uses the following logic to determine the appropriate type of response to return:

1. The MIME sub-type in the ‘accept’ HTTP header of the request is inspected. IAG uses the first MIME entry that is found in the ‘accept’ header, disregarding any specified quality factor and any subsequent MIME types.
2. If the ‘accept’ HTTP header is not present, the MIME sub-type from the ‘content-type’ HTTP header in the request is used.
3. If none of the above correspond to a response template file, the default (html) is selected.

Example

For example, consider an environment with the following error responses:

C/38cf0428.404.html
C/38cf0428.400.json

Three different clients make a request for a resource which does not exist, this would result in the error_code '38cf0428'.

Web browser client

GET /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
accept: text/html
content-type: text/html; charset=UTF-8
user-agent: mozilla/5.0 ...

In this case, the 'accept' header is present and contains the mime sub-type 'html'.

IAG will serve 'C/38cf0428.404.html' to the client with a HTTP status code 404.

API client

PUT /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
content-type: application/json; charset=UTF-8
user-agent: mobile-app-demo/1.3

In this case, the 'accept' header is not present, but a 'content-type' header is and contains the mime sub-type 'json'.

IAG will serve 'C/38cf0428.400.json' to the client with a HTTP status code 400.

Other client

GET /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
user-agent: curl/7.64.1
accept: */*

In this case, both the 'accept' and 'content-type' headers do not contain a meaningful mime sub-type, so IAG will fall back to the 'html' page.

IAG will serve 'C/38cf0428.404.html' to the client with a HTTP status code 404.

Management Pages 'page_name'

IAG provides default HTML responses for all management pages.

A complete list of the possible 'page_name' values and details about the provided default responses is below:

Error Pages 'error_code'

IAG provides HTML responses for common 'error_code' values and a HTML and JSON 'default' error response:

The 'errorcode' 'default' indicates a template that will be selected for any 'errorcode' which does not have an explicitly defined response template.

Responses can be added for 'errorcode' values not listed in the default set of responses. To customise the response for an 'errorcode' not present in the default set of responses, simply create a new response file following the naming convention and including the actual 'error_code' in the filename.

Response Macros

Contextual data can be inserted into response templates using the following macros. These macros can be used regardless of the mime sub-type.

Example

Consider the default error response, 'C/default.400.json', which contains the following content:

{
  "error_code":"%ERROR_CODE%",
  "error_message":"%ERROR_TEXT%"
}

A request is made which results in IAG needing to redirect the client. When this error response is served to the client, the %ERRORCODE% and %ERRORTEXT% macros are populated:

{
  "error_code":"0x38cf0421",
  "error_message":"Moved Temporarily"
}