How To Circulate with Draft API using Specific URL
The purpose of this guide is to demonstrate how to circulate a document to a provided URL in lieu of automatic generation.
Manually setting a circulation URL
Requirements
Existing document
Circulating to a provided URL
Requirements
You are familiar with the basic usage of the API (HTTP, Authentication, 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.
Existing document
Given two circulated documents, URWCJIIJPNGEZKZR3EZ54TO22Y
and 67B2A6C51AEE442B95F8C921FF
, start by listing the active circulations for each.
curl --request GET \ --header 'Authorization: Bearer <TOKEN>' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/circulation # RESPONSE { "circulations": [ { "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y", "website_id": "cyclist-daily", "website_url": "/wheels-news/2019/09/04/parade/", "website_primary_section": { "type": "reference", "referent": { "type": "section", "id": "/wheels-news", "website": "cyclist-daily" } }, "website_sections": [ { "type": "reference", "referent": { "type": "section", "id": "/wheels-news", "website": "cyclist-daily" } } ] }, { "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y", "website_id": "river-city-post", "website_url": "/news/2019/09/04/parade/", "website_primary_section": { "type": "reference", "referent": { "type": "section", "id": "/news", "website": "river-city-post" } }, "website_sections": [ { "type": "reference", "referent": { "type": "section", "id": "/news", "website": "river-city-post" } }, { "type": "reference", "referent": { "type": "section", "id": "/the-city", "website": "river-city-post" } } ] } ] } curl --request GET \ --header 'Authorization: Bearer <TOKEN>' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation # RESPONSE { "circulations": [ { "document_id": "67B2A6C51AEE442B95F8C921FF", "website_id": "river-city-post", "website_url": "/news/2019/09/04/man-bites-dog/", "website_primary_section": { "type": "reference", "referent": { "type": "section", "id": "/news", "website": "river-city-post" } }, "website_sections": [ { "type": "reference", "referent": { "type": "section", "id": "/news", "website": "river-city-post" } } ] } ] }
These calls provide the following information:
The document
URWCJIIJ...
is circulated on websitescyclist-daily
andriver-city-post
at URLs/wheels-news/2019/09/04/parade/
and/news/2019/09/04/parade/
respectively.The document
67B2A6C5...
is circulated on websiteriver-city-post
at URL/news/2019/09/04/man-bites-dog/
.
Circulating to a provided URL
To circulate a document at a specific URL and skip automatic URL generation, provide a website_url
value with the circulate call. website_url
must be an unused URL or occupied by a redirect targeting the same document.
For instance, attempting to circulate 67B2A6C5...
to website cyclist-daily
under the circulation URL for URWCJIIJ...
fails.
curl --request PUT \ --header 'Authorization: Bearer <TOKEN>' \ --header 'content-type: application/json' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation/cyclist-daily \ --data '{ "website_url": "/wheels-news/2019/09/04/parade/" }' # ERROR RESPONSE { "error_code": "ErrUrlAlreadyExists", "error_message": "url /wheels-news/2019/09/04/parade/ already exists for website cyclist-daily" }
Instead, circulating 67B2A6C5...
to the unused URL /wheels-news/man-bites-dog
on cyclist-daily
succeeds.
curl --request PUT \ --header 'Authorization: Bearer <TOKEN>' \ --header 'content-type: application/json' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation/cyclist-daily \ --data '{ "website_url": "/wheels-news/man-bites-dog/" }' # SUCCESS RESPONSE { "document_id": "67B2A6C51AEE442B95F8C921FF", "website_id": "cyclist-daily", "website_url": "/wheels-news/man-bites-dog/" }
Listing the documents’ circulations again shows the updated websites and URLs.
curl --request GET \ --header 'Authorization: Bearer <TOKEN>' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/circulation # RESPONSE { "circulations": [ { "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y", "website_id": "cyclist-daily", "website_url": "/wheels-news/2019/09/04/parade/", "website_primary_section": { "type": "reference", "referent": { "type": "section", "id": "/wheels-news", "website": "cyclist-daily" } }, "website_sections": [ { "type": "reference", "referent": { "type": "section", "id": "/wheels-news", "website": "cyclist-daily" } } ] }, { "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y", "website_id": "river-city-post", "website_url": "/news/2019/09/04/parade/", "website_primary_section": { "type": "reference", "referent": { "type": "section", "id": "/news", "website": "river-city-post" } }, "website_sections": [ { "type": "reference", "referent": { "type": "section", "id": "/news", "website": "river-city-post" } }, { "type": "reference", "referent": { "type": "section", "id": "/the-city", "website": "river-city-post" } } ] } ] } curl --request GET \ --header 'Authorization: Bearer <TOKEN>' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation # RESPONSE { "circulations": [ { "document_id": "67B2A6C51AEE442B95F8C921FF", "website_id": "cyclist-daily", "website_url": "/wheels-news/man-bites-dog/" }, { "document_id": "67B2A6C51AEE442B95F8C921FF", "website_id": "river-city-post", "website_url": "/news/2019/09/04/man-bites-dog/" } ] }
NoteDon’t forget the trailing slash on all urls. |