# Deep Dive: URLs in Draft API Source: https://dev.arcxp.com/publishing-platform/developer-docs/draft-api/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.](https://staging.arcpublishing.com/alc/arc-products/publishing-platform/technical-documentation-draft-api/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](https://docs.arcxp.com/alc?sys%5Fkb%5Fid=4778fbc547e65910d0cba8b5536d43f6&id=kb%5Farticle%5Fview) 2. [Circulations & Manually Set URLs](https://docs.arcxp.com/alc?sys%5Fkb%5Fid=6dd5053247229d10d0cba8b5536d43ad&id=kb%5Farticle%5Fview) 3. [Circulations & Regenerating URLs](https://docs.arcxp.com/alc?sys%5Fkb%5Fid=b0fd3a4947265910d0cba8b5536d43c0&id=kb%5Farticle%5Fview) ## 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. ```js { "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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------ | --------- | | 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: /newsurl: n/a | | | POST /draft/v1/story/ABC123/revision/published | \_id \= ABC123 headlines.basic \= Team Wins Event | \_id = ABC123 headline = 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 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------ | --------- | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ | --------- | | 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**. | Action | Draft Revision | Published Revision | Circulations | Redirects | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------- | | 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**. | Action | Draft Revision | Published Revision | Circulations | Redirects | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------ | --------- | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ----------------------------------------- | ------------------------------------------ | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------- | --------- | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------- | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------- | --------- | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------ | --------- | | 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. | Action | Draft Revision | Published Revision | Circulations | Redirects | | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------ | --------- | | 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 | |