Response Messaging service


The Response Messaging service allows Repose to intercept the response and return a pre-configured message body. Repose can be configured to provide consistent errors to users by translating the content-type of those errors.  For example, if a user asks for JSON, but the origin service normally returns a plain text message, the RMS can be configured to wrap the plain text in JSON.

Configuration

XML schema definition

The Response Messaging service is not like other Repose components which require configuration and system model changes. Repose will always run with the Response Messaging service, with or without the configuration file present.

ElementsAttributes

Required/

Optional

Description
<response-messaging>-RequiredLists status codes which allow Repose to intercept the response and return a pre-configured message body.
<status-code>-RequiredDefines the status code with which Response Messaging service will act upon.
idRequiredSets the ID of the status code rewrite. It must be unique.
code-regexRequiredDefines a regular expression that will be used to match status codes against this declaration. Please refer to http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html Java Regular Expression API.
overwriteOptional

Specifies if Response Messaging service should always overwrite the response body or only if the body is empty.  Possible values are: ALWAYS and IF_EMPTY

Default value is IF_EMPTY.

<message>

Subordinate element for

<status-code>

-Required

Defines a message that will be used when matching the parent status code. The message can be linked via the href attribute or defined in the <message> element.

  • XML messages should be included in CDATA inline.
  • The message body can contain template parameters that will be replaced by the request or response or by other server values when a status code is matched.
  • The template parameters available for use in the message body are the same as the parameters used by the SLF4J HTTP Logging filter.
media-typeRequired

Matches the content type of the message coming from the origin service. Allows different message formats for different response types.

Wildcards other than */* are not supported in media-type attribute. Configuring a media-type of */* will configure that <message> object as a catch-all.

content-typeOptional

Defines the content type on the response message returned to the client. 

Default value is text/plain.

hrefOptional

Specifies a location to an external file which contains the message to be sent.

  • If the <message> element has a value and the href attribute is configured, the Response Messaging service will use what is configured with href to send the message.
  • If the <message> element has a value and the href attribute of is modified, the Response Messaging service will need to reload the configurations to guarantee that the changes will appear in the responses. 
  • Any changes to the configuration file will cause a configuration reload.

Running on Windows

When running the Response Messaging service on Windows, there is one small change you must make.  If you wish to keep your customized response message in a file on the file system, instead of placing it directly in response-messaging.cfg.xml, the href attribute in the message element must be specified in this manner:

href="file:///C:/Users/Administrator/repose/regression-node-1/repose/node3/responsefor5xx"

Message template parameters

The message body can contain template parameters that will be replaced by request/response or other server values when a status code is matched.  The template parameters available for use in the message body are the same as the parameters used by the SLF4J HTTP Logging filter.

Notes on Response Messaging service

  • If the Response Messaging service encounters a response code and media-type combination it is not configured to handle, the Response Messaging service will not alter anything and the raw response will be returned.
  • The Response Messaging service will always use first found in regards to the status code message matched. If a return can be matched to multiple configured <status-code> elements, the Response Messaging service will only use the first configured <status-code> found.

Message template parameters test scenarios

Given the following configuration, the table below illustrates the test scenarios with requests and corresponding expected responses.

RequestResponse codeExample response expected

Request Headers:

MYDATE: Fri, 09 Mar 2012 14:56:32 GMT
accept: application/xml
x-pp-user: rms_user;q=4
x-pp-groups: unlimited;q=5

333

Response headers:
HTTP/1.1 333 333
Content-Length: 106
Content-Type: text/plain

<outer>

<groups>unlimited;q=5,IP_Standard;q=0.4</groups>

<somedate>2012-03-09T14:56:32UTC</somedate>

</outer>

Request Headers:
MYDATE: Fri, 09 Mar 2012 14:56:32 GMT
accept: application/json
x-pp-user: rms_user;q=4
x-pp-groups: unlimited;q=5

333

Response headers:
HTTP/1.1 333 333
Date: Mon, 12 Mar 2012 19:58:57 GMT
Server: Apache-Coyote/1.1
Content-Length: 83
Content-Type: text/plain


{

"groups": "unlimited;q=5,IP_Standard;q=0.4",

"mydate": "2012-03-09T14:56:32UTC"

}

Request Headers:
MYDATE: Fri, 09 Mar 2012 14:56:32 GMT
accept: text/plain
x-pp-user: rms_user;q=4
x-pp-groups: unlimited;q=5

333

Response headers:
HTTP/1.1 333 333
Content-Length: 81
Content-Type: text/plain


X-PP-Groups: unlimited;q=5,IP_Standard;q=0.4
MY-DATE: 2012-03-09T14:56:32UTC

Request Headers:
X-PP-Groups: customer
Accept: application/xml

413

Response headers:
HTTP/1.1 413 Request Entity Too Large
Retry-After: Mon, 12 Mar 2012 20:05:40 GMT
Content-Length: 207
Content-Type: text/plain

<overLimit
xmlns="http://docs.openstack.org/common/api/v1.1"
code="413" retryAfter="2012-03-12T20:05:40UTC">
<message>OverLimit Retry...</message>
<details>Error Details...</details>
</overLimit>

Request Headers:

X-PP-Groups: customer

Accept: application/json

413

Response headers:

HTTP/1.1 413 Request Entity Too Large

Retry-After: Mon, 12 Mar 2012 20:05:40 GMT

Content-Length: 207

Content-Type: application/json

{ 
    "overLimit" : 
    { 
      "code" : 413, 
      "message" : "OverLimit Retry...", 
      "details" : "Error Details...", 
      "retryAfter" : "%{Retry-After DATE ISO_8601}o" 
    } 
  } 

Request Headers:
X-PP-Groups: customer
Accept: application/xml

429

Response headers:
HTTP/1.1 429
Retry-After: Mon, 12 Mar 2012 20:05:40 GMT
Content-Length: 207
Content-Type: text/plain

<overLimit
xmlns="http://docs.openstack.org/common/api/v1.1"
code="429" retryAfter="2012-03-12T20:05:40UTC">
<message>OverLimit Retry...</message>
<details>Error Details...</details>
</overLimit>

Request Headers:

X-PP-Groups: customer

Accept: application/json

429

Response headers:

HTTP/1.1 429

Retry-After: Mon, 12 Mar 2012 20:05:40 GMT

Content-Length: 207

Content-Type: application/json

{ 
    "overLimit" : 
    { 
      "code" : 429, 
      "message" : "OverLimit Retry...", 
      "details" : "Error Details...", 
      "retryAfter" : "%{Retry-After DATE ISO_8601}o" 
    } 
  } 


JMeter logical test cases

Overwrite behavior tests

OverwriteResponse bodyExpected behavior
IF_EMPTYemptyoverwrite response body
IF_EMPTYhas contentdo not overwrite response body
ALWAYSemptyoverwrite response body
ALWAYShas contentoverwrite response body


File reading tests

HrefOverwriteResponse bodyExpected behavior
valid href to file with message contentsALWAYSN/Aoverwrite response body with message contents in file


Handle template parameters

Template parametersOverwriteResponse bodyExpected behavior

X-PP-Groups: %{X-PP-Groups}i

MY-DATE: %{MYDATE DATE ISO_8601}i

ALWAYSN/Aoverwrite response body filling in the X-PP-Groups and MYDATE template parameters with actual values from the respective request headers.