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

In this section: