How to Bulk Circulate Documents in Draft API
The purpose of this guide is to demonstrate how to circulate a document to many websites at once.
Goals
At the end of this guide, a user will be able to circulate and decirculate a document to and from many websites with one API call using the /bulk-circulation
endpoint.
Prerequisites
If you haven’t already done so, read Getting Started with the Draft API.
This guide assumes that:
You have already created a document.
The document is not circulated to any websites.
You want to circulate the document to many websites at once.
You are familiar with the basic usage of the API (HTTP, Auth, etc).
Existing Uncirculated Document
For the purpose of this guide, let’s assume our Document already exists with a Document ID of EHVJEKSMRFAMXE2BRWO2QN6XLU
.
Let’s take a look at the Document:
curl --request GET \ --header 'Authorization: Bearer ' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU # RESPONSE { "id": "EHVJEKSMRFAMXE2BRWO2QN6XLU", "type": "STORY", "draft_revision_id": "44AN46CQSZE2LDRMJSINK3O3JI" }
And its current circulations:
curl --request GET \ --header 'Authorization: Bearer ' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/circulation # RESPONSE { "circulations": [] }
We can see that:
The document is created, but not yet published
The document has no circulations
Adding Circulations
Luckily, Draft API supports a /bulk-circulation
endpoint, so that I can mass circulate with an API call.
Let's say I want to circulate my document:
On website
river-city-post
to section/news
On website
cyclist-daily
to section/local
I want
river-city-post/news
to be the primary website and section
curl --request PUT \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/circulation/bulk-circulation \ --data '[ { "document_id": "EHVJEKSMRFAMXE2BRWO2QN6XLU", "website_id": "river-city-post", "website_url": "/news/interesting-thing-happens", "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" } } ] }, { "document_id": "EHVJEKSMRFAMXE2BRWO2QN6XLU", "website_id": "cyclist-daily", "website_url": "/local/interesting-thing-at-local-place", "website_primary_section": { "type": "reference", "referent": { "type": "section", "id": "/local", "website": "cyclist-daily" } }, "website_sections": [ { "type": "reference", "referent": { "type": "section", "id": "/local", "website": "cyclist-daily" } } ] } ]'
You’ll notice that my circulation endpoint is not tied to a specific website, and I’m able to circulate to many websites by feeding in an array of circulation objects.
Verifying the Circulations
Let’s verify that the document has been circulated to both websites by using the GET /circulation
endpoint:
curl --request GET \ --header 'Authorization: Bearer ' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/circulation # RESPONSE { "circulations": [ { "document_id": "EHVJEKSMRFAMXE2BRWO2QN6XLU", "website_id": "cyclist-daily", "website_url": "/local/interesting-thing-at-local-place", "website_primary_section": { "type": "reference", "referent": { "type": "section", "id": "/local", "website": "cyclist-daily" } }, "website_sections": [ { "type": "reference", "referent": { "type": "section", "id": "/local", "website": "cyclist-daily" } } ] }, { "document_id": "EHVJEKSMRFAMXE2BRWO2QN6XLU", "website_id": "river-city-post", "website_url": "/news/interesting-thing-happens", "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" } } ] } ] }
Great. I’m circulated to both websites, and only needed to make one call.
Decirculating From Many Websites
Uh oh. Turns out my document was not supposed to go to either of those websites. Quickly, let’s reverse those circulations.
curl --request DELETE \ --header 'Authorization: Bearer ' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/bulk-circulation?website=river-city-post&website=cyclist-daily
Much like the singular decirculation endpoint, decirculating from a website removes the document from all sections on that website. By setting website query params for both websites, I can decirculate from all sections on multiple websites at once.
Verifying the Decirculation
To quickly verify my delete call worked, I can use the /circulation
endpoint:
curl --request GET \ --header 'Authorization: Bearer ' \ --url https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/circulation # RESPONSE { "circulations": [] }
And now my document is back to no circulations.
Summing it up
In this short guide, you:
# Verified the document existed GET https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU # Listed all its circulations GET https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/circulation # Circulated the document to many websites at once PUT https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/bulk-circulation { ... } # Decirculated the document from many websites DELETE https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/bulk-circulation?website=cyclist-daily&website=river-city-post