Skip to main content

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.

Example Error Response - 38cf0428 Not found

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.

Pages Description
management_pages.zip This zip file contains a directory structure including the default management responses.
error_pages.zip This zip file contains a directory structure including the default error message responses.

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.

'language_code' Language
C English
cs Czech
de German
es Spanish
fr French
hu Hungarian
it Italian
ja Japanese
ko Korean
pl Polish
pt Brazilian Portuguese
ru Russian
zh_CN Chinese (Simplified)
zh_TW Chinese (Traditional)

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:

'error_code' Default 'response_code' Description
38cf0420 301 Moved Permanently
38cf0421 302 Moved Temporarily
38cf0427 403 Forbidden
38cf0428 404 Not Found
38cf04c6 500 Server Not Responding
38cf04d7 500 Server Not Responding
38cf08cc 403 Forbidden (Time based)
default 400 Any other error code

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:

'page_name' 'response_code' 'mime_type'
help 200 (default) html
login_success 200 (default) html
logout 200 (default) html
oidc_fragment 200 (default) html
ratelimit 200 (default) html
redirect 200 (default) html
temp_cache_response 200 (default) html

Error Pages 'error_code'

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

'error_code' 'response_code' Description 'mime_type'
38cf0420 301 (default) Moved Permanently html
38cf0421 302 (default) Moved Temporarily html
38cf0427 403 (default) Forbidden html
38cf0428 404 (default) Not Found html
38cf04c6 500 (default) Server Not Responding html
38cf04d7 500 (default) Server Not Responding html
38cf08cc 403 (default) Forbidden (Time based) html
default 400 Any other error code html
default 400 Any other error code json

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.

Macro Example Description
%BACK_URL% https://demo.ibm.com Substitutes the value of the referer header from the request, or "/" if none.
%CREDATTR{name}% %CREDATTR{UID}% == 502HB8S9Q1 The value of the user credential attribute that has the specified 'name'.
%ERROR_CODE% 0x38cf0421 The numeric value of the error code.
%ERROR_TEXT% Moved Temporarily The text associated with an error code in the message catalog.
%HOSTNAME% ibm-app-gw.ibm.com Fully qualified host name.
%HTTPHDR{header}% %HTTPHEADER{HOST}% == ibm-app-gw.ibm.com Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist within the request, the macro will contain the text: 'Unknown'.
%HTTPS_BASE% https://ibm-app-gw.ibm.com:8443 Base HTTPS URL of the server, "https://host:port/".
%LOCATION% https://ibm-app-gateway/application1/ Contains the URL to which the client is being redirected. Sent only in redirects.
%METHOD% GET The HTTP method requested by the client.
%REFERER% https://demo.ibm.com/dispatch?foo=bar The value of the HTTP referer header from the request, or 'Unknown', if none.
%REFERER_ENCODED% https://demo.ibm.com/dispatch%3Ffoo%3Dbar A URI encoded version of the HTTP referer header.
%URL% /application1/demo?foo=bar A URI encoded version of the URI.
%URL_ENCODED% /application1/demo%3Ffoo%3Dbar A URI encoded version of the URI.
%USERNAME% 502HB8S9Q1 The name of the user who originated the request.

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"
}