Working with response headers
When a visitor makes a request to retrieve an asset from Brightspot, the server often includes in the response pre-configured headers. Some of those headers come from the underlying web server, and some of them are standard headers provided by Brightspot. (For an overview of request and response headers, see HTTP header.)
You can add additional response headers to implement business processes. Examples include the following:
- Requiring visitors to view an instructions page before any other page on your site.
- Displaying a message every 30 days.
- Reminding visitors to complete a customer satisfaction survey.
- Requiring web browsers to always refresh assets from the server instead of caching them.
Configuring custom response headers
To configure custom response headers:
- Click > Admin > Sites & Settings.
- In the Sites widget, select the site for which you want to configure response headers, or select Global to configure response headers for requests made to any site. (For an explanation about how Brightspot resolves multiple response headers with the same name, see the section "Resolving conflicting response headers," below.)
Under Front-End > Advanced > Custom Response Headers, click Add Custom Response Headers.
- In the Internal Name field, enter an internal name for this custom response header. You can use the internal name to quickly identify this configuration in the list of custom response headers (particularly when the configuration is collapsed).
- From the Request Matcher field, select one of the available matchers.
- To prevent Brightspot from returning this response header, toggle on Disabled. For an explanation of this toggle, see "Disabling a custom response header," below.
Complete the other fields for the selected request matcher.
For the default Path Request Matcher, configure the following fields:
- HTTP Methods—Select the methods that the request must include, or leave blank to match all HTTP methods. For a description of the HTTP methods, see HTTP request methods.
- URL Pattern—Java-compliant regular expression that the request's path must match, or leave blank to match any path. For an introduction to regular expressions, see Regex 101; for a Java-compliant regex tester, see Java Regular Expression Tester.
- Content Types—List of content types that must be associated with the request, or leave blank to match all content types.
- Projects can implement other request matchers as necessary.
- To prevent Brightspot from checking matches in subsequent response headers after satisfying the criteria in this matcher, toggle on Stop Processing. For details about this toggle, see "Interrupting rule evaluation," below.
Under Response Headers, do the following:
- Click ⨁ Add Response Header.
In the Header Name field, enter a header name.
- For a list of standard header names and associated header values, see HTTP Headers.
- Header names are not case-sensitive. Also, some browsers reformat received response headers into train case, so you may need to compare the header name you define with its rendition in the browser.
In the Header Value field, enter a value. Some response headers typically have multiple values, such as
Cache-Control: private, no-cache, max-age=0. To assign multiple values to a header, specify all of them in the Header Value field, as in the following illustration.
- Repeat steps a–c to configure additional response headers for this request matcher.
- Click Save.
How Brightspot delivers custom response headers
Brightspot examines each incoming request, and can return custom response headers associated with those requests. The following sections describe the various mechanisms Brightspot uses to determine which custom response header to return.
Matching criteria for incoming requests
Brightspot can deliver your response headers unconditionally or only for those incoming requests that satisfy criteria you define. Brightspot's standard version comes with a path request matcher that applies to incoming requests the following filters:
- Request's HTTP method, such as GET or POST. (For a description of the HTTP methods, see HTTP request methods.)
- Requested asset's content type, such as Article or Gallery.
- Request's path matching a pattern, such as starting with
/customersor containing the word
Order of matching criteria
The order of your matching criteria determines a response header's value. Suppose you design three custom response headers
Group 2, and
Group 3, each with its own matching criteria, as in the following illustration.
Brightspot evaluates all the matching criteria in order, and the header receives the value based on the last rule successfully evaluated. In this example, Brightspot evaluates first the criteria in
Group 1, then in
Group 2, and then in
Group 3. If an incoming request matches all three rules, then the header receives the value assigned in
Group 3. If an incoming request matches the first two rules, then the header receives the value assigned in
Disabling a custom response header
Group 2, and
Group 3 set a value for the header
Header-A, as in the following example.
|Custom response header
Normally, a request satisfying the matching criteria of all three groups applies the value configured in the last matching group. In this example, Brightspot could send any of the following headers, depending on the last match satisfied:
Header-A: 505, or
If you want to avoid the possibility of sending
Header-A: 505, you need to disable the evaluation in
Group 2, as in the following illustration.
Group 3 follows disabled
Group 2, Brightspot sends
Header-A: 510 if the match in
Group 3 is successful.
Interrupting rule evaluation
By default, Brightspot evaluates all the rules in order, and assigns a header's value based on the last matching rule. You can interrupt the sequence of rule evaluation.
Group 2, and
Group 3 set a value for
Header-A. If you stop evaluation at
Group 2, then Brightspot sends one of the following headers:
Header-A: 500configured in
Group 2is not a match)
Header-A: 505configured in
Group 2is a match)
If you want to avoid sending the header configured in
Group 3, you need to stop processing in
Group 2, as in the following illustration.
Disabling a rule takes precedence over rule interruption. If you stop evaluation at
Group 2 and also disable
Group 2, then Brightspot proceeds to
Group 3 and assigns to
Header-A the value determined in
Group 1 (if
Group 3 is not a match) or the value in
Group 3 (if
Group 3 is a match).
Resolving conflicting response headers
If you configure a response header with the same name more than once, Brightspot uses the following logic to determine which value to return.
- Determine from which site to send the header (first a specific site, then global).
- Send the header's value defined last in the UI.
Example 1: Same header configured at global and site levels
A header name at the site level has higher precedence than the same name at the global level. For example, you have a header-value pair
Cache-Control: public defined for the site
Brightspot, and a header-value pair
Cache-Control: private defined for the global site. Visitors to the site
Cache-Control: public , and visitors to all your other sites receive
Example 2: Same header configured multiple times in same site
When the same header is defined more than once within the same site, the one appearing last in the Custom Response Headers widget has the highest precedence. Below are two examples.
|In this scenario, the site has a single custom response header with two response headers having the same name. Brightspot returns the last one in the list,
|In this scenario, the site has multiple custom response headers, each with a response header having the same name. Brightspot returns the last one in the list,
Example: Controlling browser caching
A high-volume news site posts headlines and images to its homepage every few minutes. To ensure their visitors always see the latest headlines, management requires that the visiting browsers do not cache any content from previous visits to the homepage. The following illustration implements this policy.
Referring to the previous illustration, Brightspot returns a custom header when the incoming request satisfies the following criteria:
- The request uses the method GET or POST.
- The requested asset is a homepage.
When these two criteria are met, Brightspot returns the response header
Cache-Control: public, max-age=0. Because the toggle Stop Processing is on, once these rules are satisfied Brightspot does not check any subsequent rules that may deliver a different caching policy to the browser.