How to Use Draft API to Regenerate and Redirect a Document URL
The purpose of this guide is to be a walkthrough on how to re-generate an URL for an existing document on any publish after its first.
Requirements
This guide assumes that:
You have already created a document
The document has been published at least once previously
The document is already circulated
You want to re-generate the URL based on a pre-configured format rule
You are familiar with the basic usage of the API (HTTP, Auth, etc).
If you have not used the API before, or need a refresher, refer to the Draft API documentation and Getting Started with the Draft API.
Initial concepts
On the Arc Platform, there are two types of content: historical content, and new content. Historical content already has a URL. New content is new, and therefore, at some point before publication, needs a URL to be generated (ie decided) for it.
The way URLs are generated is by using rules. I.e., if the content matches certain criteria, then we will generate its URL using a predefined set of rules. For example, this could be:
If the content is a
story(as opposed to a gallery or video)URL might be (space for clarity):
/ YEAR / MONTH / DAY - ARTICLE_TITLE
Such rules are called formats. As described above, a format is:
A set of conditions (which can be empty, like a "match all")
A pattern describing how the URL is generated from known information (metadata and fields)
A priority, to ensure that more specific rules are applied first, and global rules last
Formats are specific to a particular website. If you operate in multi-site mode, you will need to define formats for each of your websites.
Checking existing format rules
You can request the list of format rules currently available for a specific website:
curl --request GET \
--header 'Authorization: Bearer <TOKEN>' \
--url https://api.{{org}}.arcpublishing.com/draft/v1/url-format-rule/<website_id>
Response:
{
"rules": [
{
"id": "1557513374591",
"format": "author/%lastName%_%firstName%/",
"priority": 10,
"criteria": {
"type": "author"
}
},
{
"id": "default",
"format": "%publish_date|year()%/%publish_date|month()%/%publish_date|day()%/%headlines.basic|slugify()%/",
"priority": 100000
}
]
}
Existing Document
Let's assume we have an existing document, FPZWVDXQWRE75FS75LZWW3IQAE. Let's take a look at the document:
curl --request GET \
--header 'Authorization: Bearer <TOKEN>' \
--url https://api.{{org}}.arcpublishing.com/draft/v1/story/5YR4HVCCC5HQ5AVVRR65O7CKTM
Response:
{
"id": "FPZWVDXQWRE75FS75LZWW3IQAE",
"type": "STORY",
"created_at": "2020-09-22T12:37:01.249Z",
"first_published_at": "2020-09-22T12:37:13.498Z",
"last_published_at": "2020-09-22T12:37:13.498Z",
"draft_revision_id": "BHMYUCJGSBAFLDUAJ6RPG36VMY",
"published_revision_id": "4NYK35VPJBH7LA6W2YEOKD3RI4"
}
As we can see from this response, our Document has already been published, since it has a published_revision_id.
Let’s now ensure that our document has been circulated:
curl --request GET \
--header 'Authorization: Bearer <TOKEN>' \
--url https://api.{{org}}.arcpublishing.com/draft/v1/story/FPZWVDXQWRE75FS75LZWW3IQAE/circulation
Response:
{
"document_id": "FPZWVDXQWRE75FS75LZWW3IQAE",
"website_id": "the-herald",
"website_url": "/2020/09/28/thing-happens-at-place/",
"website_primary_section": {
"type": "reference",
"referent": {
"type": "section",
"id": "/news",
"website": "the-herald"
}
},
"website_sections": [
{
"type": "reference",
"referent": {
"type": "section",
"id": "/news",
"website": "the-herald"
}
},
{
"type": "reference",
"referent": {
"type": "section",
"id": "/sports",
"website": "the-herald"
}
}
]
}
We can see that the Document has been circulated to two different sections on The Herald, /news and /sports. We can also see that it has a website_url assigned to it, based on its publish date and headline. This website_url was auto-generated once the Document was both published and circulated.
Editing the Document
My Document is already published and circulated, but I just decided that I wanted to change the headline to be more descriptive. To do this, I’ll quickly create a new draft revision with my updated headline.
curl --request PUT \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--url https://api.{{org}}.arcpublishing.com/draft/v1/story/FPZWVDXQWRE75FS75LZWW3IQAE/revision/draft
--body '{
"document_id": "FPZWVDXQWRE75FS75LZWW3IQAE",
"ans": {
"canonical_website": "the-herald",
"headlines": {
"basic": "Team Wins Event in City!"
},
"type": "story",
"version": "0.10.5",
"slug": "team_wins_event_in_city"
},
"type": "DRAFT"
}'
Response:
{
"id": "HUS4KJACJVCGRL7O55H5USGNTA",
"document_id": "FPZWVDXQWRE75FS75LZWW3IQAE",
"ans": {
"additional_properties": {
"has_published_copy": true
},
"canonical_website": "the-herald",
"created_date": "2020-09-22T12:45:25.219Z",
"headlines": {
"basic": "Team Wins Event in City!"
},
"last_updated_date": "2020-09-22T12:45:25.219Z",
"owner": {
"id": "staging"
},
"slug": "team_wins_event_in_city",
"type": "story",
"version": "0.10.6"
},
"created_at": "2020-09-22T12:45:25.219Z",
"type": "DRAFT"
}
Now that we’ve updated our story, we want to go ahead and re-publish this new revision. However, since I updated the headline, I really want my URL to re-generate to match this headline. Luckily, our publish endpoint has a regenerate query parameter that can force this for you, without needing to go through the hoops of re-circulating the document.
Let’s use the new parameter here:
curl --request POST \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--url https://api.{{org}}.arcpublishing.com/draft/v1/story/FPZWVDXQWRE75FS75LZWW3IQAE/revision/published?regenerate=true
Response:
{
"id": "KIH7H2OHW5FJJJBJAOCKPP2CPM",
"document_id": "FPZWVDXQWRE75FS75LZWW3IQAE",
"ans": {
"additional_properties": {
"has_published_copy": true
},
"canonical_website": "the-herald",
"created_date": "2020-09-22T12:49:57.552Z",
"display_date": "2020-09-22T12:37:13.498Z",
"first_publish_date": "2020-09-22T12:37:13.498Z",
"headlines": {
"basic": "Team Wins Event in City!"
},
"last_updated_date": "2020-09-22T12:49:57.552Z",
"publish_date": "2020-09-22T12:49:57.652Z",
"slug": "team_wins_event_in_city",
"type": "story",
"version": "0.10.6"
},
"created_at": "2020-09-22T12:49:57.552Z",
"type": "PUBLISHED"
}
Now I can see that the latest published revision has my headline changes. Let’s check the circulation of my Document to ensure that the website_url was updated correctly:
Response:
{
"document_id": "FPZWVDXQWRE75FS75LZWW3IQAE",
"website_id": "the-herald",
"website_url": "/2020/09/22/team-wins-event-in-city/",
"website_primary_section": {
"type": "reference",
"referent": {
"type": "section",
"id": "/news",
"website": "the-herald"
}
},
"website_sections": [
{
"type": "reference",
"referent": {
"type": "section",
"id": "/news",
"website": "the-herald"
}
},
{
"type": "reference",
"referent": {
"type": "section",
"id": "/sports",
"website": "the-herald"
}
}
]
}
Awesome. Now we can see that our document has a new URL based on this new headline.
Unfortunately, we had already posted the old URL on social media. Let’s check and ensure that the old URL has a redirect to this new one in order to keep traffic flowing to my story.
curl --request GET \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--url https://api.{{org}}.arcpublishing.com/draft/v1/story/FPZWVDXQWRE75FS75LZWW3IQAE/redirect/the-herald
Response:
{
"redirects": [
{
"website_id": "the-herald",
"website_url": "/2020/09/28/thing-happens-at-place/",
"document_id": "FPZWVDXQWRE75FS75LZWW3IQAE",
"created_at": "2020-09-28T12:21:27.806Z",
"updated_at": "2020-09-28T12:22:43.842Z"
}
]
}
Awesome. Now I can see that my Document has redirect from its old URl. My URL has been successfully regenerated!