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:

1. Click menu > Admin > Sites & Settings.
2. 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.)

3. Under Front-End > Advanced > Custom Response Headers, click add_circle_outline Add Custom Response Headers.

   

4. 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).
5. From the Request Matcher field, select one of the available matchers.
6. To prevent Brightspot from returning this response header, toggle on Disabled. For an explanation of this toggle, see "Disabling a custom response header," below.

7. Complete the other fields for the selected request matcher.

   1. For the default Path Request Matcher, configure the following fields:

      1. 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.
      2. 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.
      3. Content Types—List of content types that must be associated with the request, or leave blank to match all content types.
   2. Projects can implement other request matchers as necessary.
8. 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.

9. Under Response Headers, do the following:

   1. Click ⨁ Add Response Header.

   2. 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.

   3. 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.

      

   4. Repeat steps a–c to configure additional response headers for this request matcher.
10. 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 /customers or containing the word integrations.

Order of matching criteria

The order of your matching criteria determines a response header's value. Suppose you design three custom response headers Group 1, 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 Group 2.

Disabling a custom response header

Suppose Group 1, Group 2, and Group 3 set a value for the header Header-A, as in the following example.

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: 500, Header-A: 505, or Header-A: 510.

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.

Because 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.

Suppose Group 1, 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: 500 configured in Group 1 (if Group 2 is not a match)
• Header-A: 505 configured in Group 2 (if Group 2 is 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.

1. Determine from which site to send the header (first a specific site, then global).
2. 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 Brightspot receive Cache-Control: public , and visitors to all your other sites receive Cache-Control: private.

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, Header-A: 505.	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, Header-A: 510.

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:

1. The request uses the method GET or POST.
2. 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.