Skip to content
Arc XP
Product Documentation

Deep Dive: URLs in Draft API

Overview

This guide aims to walk through 15 of the most common workflows to outline when and how a URL will be created for a document. Each table below represents a single workflow, highlighting the Draft Revision, Published Revision, Circulations, and Redirects resulting from each Action taken in Draft API.

Read also our URL Generation Overview.

Prerequisites

Before walking through this guide, we highly suggest having an understanding of how Circulations work in Draft API, including the difference between generated URLs and manually set URLs:

  1. Circulations & URL Generation
  2. Circulations & Manually Set URLs
  3. Circulations & Regenerating URLs

Assumptions

For the sake of brevity, the full circulation objects are not included in the tables below. A full circulation request includes the following object. For our examples, we will just be highlighting a single section ID and URL field.

{
   "website_url": "", // included in examples below
  "website_primary_section": {
    "type": "reference",
    "referent": {
      "type": "section",
      "id": "/news",
      "website": "the-herald"
    }
  },
  "website_sections": [
    {
      "type": "reference",
      "referent": {
        "type": "section",
         "id": "/news", // included in examples below
        "website": "the-herald"
      }
    }
  ]
}

The exact URL being generated for a document is dependent on your organization’s URL format rules, websites, and section names. Throughout this guide, we’ll make some assumptions about these for our organization. Please note that your exact URLs will vary.

URL Format Rule:

 /{websites.the-herald.website_section}/{publish_date}/{headlines.basic}

Websites and Sections:

  • Website ID: the-herald
  • Section IDs: /news, /sports

Publish Date:

We will assume that unless stated otherwise, all publishes happen on July 1, 2021

Workflows

1. Classic Publishing Workflow

This workflow outlines the most basic and usual case for working in Draft API.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{ website_url: ' ', website_section: /news }		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123 headline = Team Wins Eventsection: /news
url: /news/2021/07/01/team-wins-event/
PUT /draft/v1/story/ABC123/revision/draft_id = ABC123
headlines.basic = Team Loses Event		_id = ABC123
headline = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headline = Team Loses Event		_id = ABC123
headline = Team Loses Event		section: /news
url: /news/2021/07/01/team-wins-event/

2. Publishing using “regenerate” Parameter

This workflow outlines using the ?regenerate=true parameter on publish requests in order to force a new URL to be generated. This workflow creates a redirect.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{ website_url: ' ', website_section: /news }		_id = ABC123
headline = Team Wins Event		section: /news
url: n/a
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/
PUT /draft/v1/story/ABC123/revision/draft_id = ABC123
headlines.basic = Team Loses Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/
POST /draft/v1/story/ABC123/revision/published**?regenerate=true**_id = ABC123
headlines.basic = Team Loses Event		_id = ABC123
headlines.basic = Team Loses Event		section: /news
url: /news/2021/07/01/team-loses-event/		website_url: /news/2021/07/01/team-wins-event/
_id: ABC123

3. Circulating after Publishing

This workflow outlines URL generation when circulation occurs after publishing.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: ' ', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/

4. Adding Additional Sections

This workflow outlines adding additional information, like additional sections, to your circulation after publishing.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website\_url: ' ', website\_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/news/2021/07/01/team-wins-event', website_sections: [/news, /sports]}		_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		sections: [/news, /sports]
url: /news/2021/07/01/team-wins-event/

5. Forcing Regeneration through Circulating

This workflow outlines how setting website_url: '' to an empty string can also force the regeneration of a URL. While this works, we recommend using the publish with ?regenerate=true workflow outlined in Flow 2 above. The workflow results in a redirect.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/my-old-cms-url', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /my-old-cms-url
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /my-old-cms-url
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: ' ', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/		website_url: /my-old-cms-url
_id: ABC123

6. Changing the Set URL

This workflow outlines how to change a manually set URL. The workflow results in a redirect.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/my-old-cms-url', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /my-old-cms-url
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /my-old-cms-url
POST /draft/v1/story/ABC123/circulations/the-herald {website_url: '/different-preset-url/', website_section: /news}_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /different-preset-url		website_url: /my-old-cms-url
_id: ABC123
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/a-third-url/', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /a-third-url		website_url: /my-old-cms-url
_id: ABC123
website_url: /different-preset-url/
_id: ABC123

7. Setting a new URL after Publish

The workflow outlines how to manually set a URL on a circulation for a document that already has a generated URL. This workflow results in a redirect.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '',website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/preset-url', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /preset-url/		website_url: /news/2021/07/01/team-wins-event/
_id: ABC123

8. Setting a new URL before Publish

The workflow outlines how to manually set a URL on a circulation for a document that does not currently have a URL associated.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
POST /draft/v1/story/ABC123/circulations/the-herald {website_url: '/my-old-url', website_section: /news}_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /my-old-url
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /my-old-url

9. Updating a Set URL before Publish

This workflow outlines how to change your manually set URL before a document is published. This workflow results in a redirect.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/my-old-cms-url', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /my-old-cms-url
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/another-old-url' , website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /another-old-url
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /another-old-url		website_url: /my-old-cms-url
_id: ABC123

10. Forcing Regeneration through Circulating, Prior to Publish

This workflow outlines how setting website_url: '' to an empty string can also force the regeneration of a URL. While this works, we recommend using the publish with ?regenerate=true workflow outlined in Flow 2 above whenever possible.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/my-old-cms-url', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /my-old-cms-url
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/

11. Decirculating

This workflow outlines how decirculating a document impacts URLs.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: ' ', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/
DELETE /draft/v1/story/ABC123/circulations/the-herald_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		[ empty ]
At this point, the document is equivalent to having never been circulated.

12. Unpublishing

This workflow outlines unpublishing a document.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: ' ', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/
DELETE /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/01/team-wins-event/

13. Scheduled Publish with Automatic URL Generation

This workflow outlines how a scheduled publish (completed via either Composer or Content Operations API) can still generate a URL on your behalf.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: ' ', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
--- Schedule Publish on July 30, 2021 ---------------
PUT /draft/v1/story/ABC123/revision/draft_id = ABC123
headlines.basic = Team Loses Event		section: /news
url: n/a
--- Schedule Time Elapses ---------------
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Loses Event		_id = ABC123
headlines.basic = Team Loses Event		section: /news
url: /news/2021/07/01/team-loses-event/

14. Setting URL before Scheduled Publish Time

This workflow outlines how to manually set your URL prior to a scheduled publish (completed via either Composer or Content Operations API). This workflow takes advantage of Draft API’s /resolve endpoint to mimic URL generation ahead of time. This should be used when you need a URL ahead of time for your document that looks as if it was generated automatically. In this flow, updates made to a document between setting the URL and scheduled publish will not be reflected in the URL.

ActionDraft RevisionPublished RevisionCirculationsRedirects
POST /draft/v1/story_id = ABC123
headlines.basic = Team Wins Event
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: ' ', website_section: /news}		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: n/a
POST /draft/v1/url-format-rule/the-herald/resolve with mocked publish_date data
Returns: /news/2021/07/30/team-wins-event/		------------
POST /draft/v1/story/ABC123/circulations/the-herald
{website_url: '/news/2021/07/30/team-wins-event', website_section: /news}		_id = ABC123 headlines.basic = Team Wins Event_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/30/team-wins-event/
--- SCHEDULE PUBLISH FOR JULY 30, 2021 ---------------
POST /draft/v1/story/ABC123/revision/published_id = ABC123
headlines.basic = Team Wins Event		_id = ABC123
headlines.basic = Team Wins Event		section: /news
url: /news/2021/07/30/team-wins-event