Working with response headers

Understanding request and response headers

The Internet is built of clients (web browsers, mobile apps, ATM machines, etc.) that request data from servers. In the early days of the Internet, the client simply sent a message to a server indicating the file it wanted to retrieve, as in the following example.

GET /cms-use-cases.html

The server read the message, and returned to the client the requested file.

Explore CMS use cases

Very quickly, it became apparent that simple requests and responses were not enough. Both clients and servers wanted to include additional capabilities and address security concerns. As a result, both clients and servers now include headers in their messages. Clients send request headers to the server, and servers send response headers back to the client. The following table provides samples of common request and response headers.

Header	Purpose	Example	Usage
Request headers
Cookie	Sends additional information to the server, such as an account number or user ID.	`Cookie: id=123456789`	After receiving the user ID in the cookie, the server can return to the client any special resources associated with that ID. (There are many parts of Brightspot that depend on the user ID, including profile settings and permissions. For example, you created your own dashboard. Brightspot stores that dashboard under your user ID. When you select menu> Dashboard, your browser sends your user ID in a cookie to Brightspot. If there is a dashboard associated with your user ID, Brightspot sends it back to your browser.)
User-Agent	Informs the server the type of browser that is sending the request.	`User-Agent: Mozilla/5.0`	To verify that this is a valid request from a browser, the server can check that this header exists. Additionally, web sites can send different responses depending on the user agent.
Response headers
Set-Cookie	Sends a cookie to the client. This is often necessary so the client and server can maintain a session over several requests. In many scenarios, when a visitor logs in to a web site, the server responds by setting a cookie with a user ID. Every time the visitor requests something from the web site, the client sends the ID number it received.	`Set-Cookie: id=123456789`	After an editor logged in, the server looked up the corresponding user ID and sent it back to the browser. The client then stores the user ID in a cookie. For a description of the interaction between a client, server, and cookie, see the Cookie request header, above).
Cache-Control	Instructs the client how to store and use information received from the server.	`Cache-Control: max-age=0`	The server informed the client that information returned from the server continues to match what is on the server for zero seconds. In effect, the server cannot guarantee that the same request will generate the same response. This is a typical setting in highly interactive web sites such as Brightspot.

Configuring custom response headers

When a client makes a request to retrieve something from Brightspot, the client receives a response with pre-configured headers. Some of those headers come from the underlying web server, and some of them are standard cookies provided by Brightspot. You can add additional response headers.

To configure custom response headers:

Click menu > 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 all sites. (Any response headers you configure for the global site are sent to the clients in addition to any headers you configure for specific sites.)
Under Front-End > Advanced > Custom Response Headers, click add_circle_outline Add Custom Response Header.

Adding a custom response header
Using the following table as a reference, configure a custom response header.
Repeat steps 4–5 to configure additional custom response headers.
Click Save.

Field	Description
Internal Name	Enter an internal name for this custom response header.
Request Matcher	Configure a set of criteria that the request must satisfy in order to return this response header to the client. Disabled—No matching is required; Brightspot unconditionally returns this response header. HTTP Methods—List of methods that the request must include. For a description of the HTTP methods, see HTTP request methods. URL Pattern—Regular expression that the request's URL must match. For an introduction to regular expressions, see Lesson: Regular Expressions. Content Types—List of content types that must be associated with the request. For example, you select Tag in this list. A client sends a request for `/cms-use-cases`. If the asset at `/cms-use-cases` is a tag, then Brightspot returns this response header. Stop Processing—If the request satisfies these matching criteria, then Brightspot does not check for matches in other response headers.
Response Header	Click add_circle_outline, and add a Header Name and associated Header Value. Repeat to add additional response headers for this custom response header. For a list of standard header names and associated header values, see HTTP Headers. Header names at the site level have higher precedence than the same name at the global level. For example, if 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`.

Referring to the previous illustration, Brightspot returns a custom header when the received request satisfies the following criteria:

The request uses the method GET or POST.
The requested file name ends with .js.
The requested asset is an article.

When those three criteria are met, Brightspot returns the header Content-Type: text/javascript; charset=utf-8.

Tutorial: Setting a cookie

Management has decided that all visitors must view an instructions page before they can continue using the site. The way to tell that a visitor has viewed the instructions page is to use a response header to set the cookie viewedInstructions=yes after viewing the page /instructions. The following tutorial explains how to configure this scenario.

Click menu> Admin > Sites & Settings > Sites > Global.
Under Front-End > Advanced > Custom Response Headers, click add_circle_outline Add Custom Response Header.
In the Internal Name field, enter Viewed Instructions.
In the URL Pattern field, enter ^/instructions$. Your widget looks similar to the following:

Request matching criteria for custom response header
Under Response Headers, click add_circle_outline Add Response Header.
In the Header Name field, enter Set-Cookie.
In the Header Value field, enter viewedInstructions=yes. Your widget looks like the following:

Custom response header
Click Save.

A visitor viewing the page /instructions can inspect the cookie set by the server.

Set cookie from a custom response header