What are the different kinds of redirects in Arc XP?

Most URLs in Arc XP are generated through Composer using some combination of publish date and a slugified headline. For this example, let’s assume we’ve published a story on February 26, 2020 with the misspelled headline “Team Wins Evnt", which results in a URL of /sports/team-wins-evnt/. You can see this basic story creation and reader flow in the following diagram.

This story has already been published, and our dedicated readers have already shared it with all of their friends, so we can’t just change the URL and cause all of the previous links to start returning an HTTP 404 error.

This is where we can use a Story Redirect.

After correcting the headline in Composer, we can click the Regenerate button to regenerate the new URL from the new headline. When we do this, Composer is aware that the old URL is still out there somewhere and auto-creates a Story Redirect from the old URL to the new.

On the reader side, when a reader navigates to the old URL, PageBuilder uses a Content API content source to look up the content associated with that URL. In most cases, the Content API response is a content object, representing a story or some other piece of content.

In the case of a story redirect, however, the Content API response is actually a redirect object and includes a PB-Canonical-Redirect header, which tells PageBuilder to look for a redirect URL and send the reader to that URL instead.

We updated the headline and now the URL is redirecting correctly. Unfortunately, we called this sporting event too soon, and it turns out the team actually lost.

As the story develops, we may need to keep updating the headline and story, and in doing so, regenerating a new URL for the new headline.

Luckily, this works in exactly the same way as correcting a misspelling with a story redirect, as seen here.

You can create redirects in a few different places: using the Draft API, the Canonical URLs UI, in Arc XP Origin, and directly at the CDN level. To determine which method is the best option for your vanity redirect, use the following flow chart.

The first thing to check is the original URL’s domain (the “from URL”). If this domain is not hosted by Arc XP, it may not be possible for Arc XP to redirect.

For example, if you have two sites, mainsite.com and secondsite.com, and only one of them (mainsite.com) is hosted by Arc XP, you:

Next, if the original URL has query parameters, you must create those parameters at the CDN level through a support ticket.

The next question is around the number of vanity redirects you need to create. If you have many redirects to make that follow a pattern, you have the option to create a regex-based PageBuilder resolver that programmatically redirects.

In the event that you’re creating only a single vanity redirect, a single-site organization can use the Canonical URLs UI. Otherwise, you can use the Draft API.

Redirects created in the Draft API are ultimately stored and served by the Content API. In order for a redirect stored in the Content API to work, you must have a resolver that matches the original URL that is responsible for sending the request to the Content API. For in-depth documentation, see Configuring resolvers. The following screenshot shows a common use case: a resolver designed to match several short vanity redirects and send those to the Content API. You must set the priority high enough that they are above any other potentially matching resolvers (for example, a resolver that sends matching paths to site service for rendering section fronts).

Note: The template is not shown in the previous image in order to avoid confusion and because it wouldn’t be used anyway. Because it’s a required field, feel free to use your main article template, but here’s why it doesn’t matter: When the redirect resolver matches a request, it captures the URL and sends it to the Content API as the canonical URL. Content API responds with a special header that causes PageBuilder Engine to automatically issue an HTTP 302 response rather than sending the response payload to the default template. The system then parses the location specified in the HTTP 302 through the stack of resolver patterns, and when a match is found, the template specified in that resolver is used. Visually, this process looks like this:

/shopping2020/ => redirect resolver match => content api => 302 /shopping/lists/[...]/ => article resolver match => content api => template

If you are using the included_fields query parameter to filter the data returned from the Content API, you must include redirect_to as one of the fields; otherwise, PageBuilder Engine does not know where to send the redirect and does not automatically issue an HTTP 302 response.

Consult the Draft API documentation for more information about redirects. The following example illustrates creating a redirect from the short URL /2020shoppinglist/ configured in the previous resolver screenshot to the longer destination URL.

curl --location --request POST 'https://api.<arc-org-id>.arcpublishing.com/draft/v1/redirect/<website>/2020shoppinglist/?website=<website>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "redirect_to": "/shopping/lists/best-gift-ideas-for-the-2020-holiday-season/"
}'

You should get a response back similar to this:

{
    "website_id": "<website>",
    "website_url": "/2020shoppinglist/",
    "redirect_to": "/shopping/lists/best-gift-ideas-for-the-2020-holiday-season/",
    "created_at": "2020-12-16T20:49:01.579Z",
    "updated_at": "2020-12-16T20:49:01.579Z"
}

Note: Don’t forget the trailing slash on all URLs. The Arc XP delivery configurations automatically append trailing slashes when they are not used so it’s best to stay consistent.

This win-turned-loss event is historic, and now we want to create a feed of stories about it on our home page. Unfortunately, a partner site hosts some of these stories outside of Arc XP.

In this scenario, we can use a forward redirect to show the story on our site but still link to another site when someone clicks the article. To do this, we create a stub of the Story in Composer that has the information we need for our feed (like a headline, author, and promo image).

We can then add a forward URL from the Composer Meta tab (could also be on the Planning tab), which gets stored in the related_content.redirect section of the ANS.

When a reader then goes to the our home page, they’re able to see the story in the feed with the information provided in Composer. When they click the story though, the Content API returns a PB-Canonical-Redirect header to PageBuilder, which in turn causes PageBuilder to look for the redirect URL in the related_content object and send the reader to that URL instead.

In your custom content source, if you you are is using resolve method, there are no additional steps. Engine will read the header and return a redirect. However, if your content-source is using a fetch implementation where you are responsible to handle Content API call as well as handling the response and returning Redirect header. In order to do this, you will need to add a check for the related_content.redirect field in the Content API response, and return a response with redirect status code and the URL. A sample implementation of handling redirects may look like this:

const get = require("lodash.get");

const RedirectError = (location, message = "Redirect", code = 302) => {
    const err = new Error(message);
    err.statusCode = code;
    err.location = location;
    return err;
};

[...]
.then((response) {
    const content = response.data;
    const contentType = content.type;
    const redirectUrl = get(content, "related_content.redirect[0].redirect_url", null) || get(content, "redirect_url", null);

    if (contentType && (contentType === "story" || contentType === "redirect") && redirectUrl) {
        throw RedirectError(redirectUrl);
    }
})
[...]

Arc XP has launched the Redirect UI to configure the redirects at the CDN level, such as:

Note: For creating an alternate origin configuration that serves some portion of content from a non-Arc XP-hosted environment (but may not reflect this in the browser URL bar), open a support ticket.