How Draft API Uses Format Rules to Generate Content URLs

First, let’s take a look at a URL.

https://the-herald-news.com/sports/baseball/2021/05/03/team-wins-series/

In Arc XP, when we talk about URL generation, we focus on the piece of the URL after your base path. In this example, we’re looking specifically at how we got to /sports/baseball/2021/05/03/team-wins-series/.

Generating this URL is possible due to URL Format Rules, which are a set of rules that your organization creates to determine how the Draft API should generate a URL. URL Format Rules are composed of two parts: criteria and format.

The criteria determines when the rules use a specific format. Often, your organization may want to generate URLs differently depending on the type of content. Author pages, for example, do not have circulations and, therefore, shouldn’t use a section field.

You define the criteria as a JSON object. If the piece of content that the Draft API is evaluating has fields that fully match the criteria, the Draft API uses that format. If the content matches multiple criteria, then the Draft API uses their priority to determine which format to use. For example, if the criteria is:

{
    "type":"story",
    "subtype":"blog-post"
}

Then any piece of content that has type of story and subtype of blog-post match this criteria and use its format.

The format is the actual rule to follow when generating the URL. The format describes which pieces of ANS fields will be picked to be part of the generated URL. Any ANS field that exists on a published piece of content can be selected as a piece of the URL format. The URL format can also apply several built-in functions to the ANS fields that can change the field's value on the fly, for example by applying a slugify function to a headline. Most URL formats use a combination of dates, sections, headline, or ANS id to form a unique URL.

Let’s take a look at some example formats:

/%display_date|year()%/%display_date|month()%/%display_date|day()%/%headlines.basic|slugify()%/

This example uses a combination of display_date and headline to ensure a unique URL. First, the format uses functions to specifically select the display date value, and pick out its year, month, and day. Then, it applies the slugify() method on the article's headline. This example results in a URL like /2020/05/03/my-headline-here/.

Now let's consider a more complicated example.

/video%websites.the-herald.website_section%/%headlines.basic|slugify()%/%publish_date|year()%/%publish_date|month()%/%publish_date|day()%/%_id%_video.html

In this example, the format uses a combination of ANS fields and static text to make a URL. It also makes use of the websites object, which can pull circulation information and insert it into the URL. This example results in a URL like /video/sports/baseball/my-headline-here/2020/05/01/ABC123_video.html

In the most basic case, your URL generates when you have both circulated and published a document.

Draft API also offers a /resolve endpoint that can mimic URL generation ahead of publish time. In those cases, your flow may look more like:

Some risk exists with this method, as many URL formats use date fields that may not be correctly populated until publish time. You can mimic these fields ahead of time if you know when your story will be published. For this reason, this methodology is often used with Scheduled Publish workflows where the story URL needs to be known before the publication actually occurs.

Depending on which version of ANS your stories adhere to, you can use several ANS fields to add a section to a URL.

After setting up your URL Format Rules, you may still run into URL Generation Failure errors in Composer. If so, you can follow the steps here before creating an ACS Ticket to see if you can resolve the issue.