How To Change The Circulation of a Document

The purpose of this guide is to demonstrate how to circulate a document to an additional website.

Requirements

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 circulated to 1 website.
You want to circulate the document to an additional website.
You are familiar with the basic usage of the API (HTTP, Auth, etc).

Existing document

Let's assume we have an existing document, ZHXE3Y6OJVAUFDJIM3M43AV5KM. Let's take a look at the document:

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM

# RESPONSE
{
  "type": "STORY",
  "id": "ZHXE3Y6OJVAUFDJIM3M43AV5KM",
  "created_at": "2019-09-01T09:00:00Z",
  "updated_at": "2019-09-05T09:00:00Z",
  "draft_revision_id": "U633XTDDYBGMVOUNWAWW522KAQ",
  "published_revision_id": "SRZHEJXNFBB55GBVPFAVJXVSZ4",
  "first_published_at": "2019-09-05T09:00:00Z",
  "last_published_at": "2019-09-05T09:00:00Z"
}

And its current circulations:

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM/circulation

# RESPONSE
{
  "circulations": [
    {
      "document_id": "ZHXE3Y6OJVAUFDJIM3M43AV5KM",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/parade",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "id": "/news",
          "type": "section",
          "website": "river-city-post"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "id": "/news",
            "type": "section",
            "website": "river-city-post"
          }
        },
        {
          "type": "reference",
          "referent": {
            "id": "/the-city",
            "type": "section",
            "website": "river-city-post"
          }
        }
      ]
    }
  ]
}

We can see that:

The document is circulated to a single website, river-city-post
On river-city-post, it has the URL /news/2019/09/04/parade
On river-city-post, it belongs to 2 sections: /news (primary) and /the-city

Let's now circulate the document to another website, cyclist-daily, in the /wheels-news section.

Adding a second website

On each website, a document can belong to one or more sections. Whether the document belongs to one, two, or many sections, there is usually a section that is considered "primary". This section is the "home", so to speak, of the document. It is also usually reflected in the URL of the document. Additional sections increase reach and readership. With that in mind, let's add the extra circulation:

curl --request PUT \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM/circulation/cyclist-daily \
  --data '{
      "document_id": "ZHXE3Y6OJVAUFDJIM3M43AV5KM",
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/2019/09/04/parade",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "id": "/wheels-news",
          "type": "section",
          "website": "cyclist-daily"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "id": "/wheels-news",
            "type": "section",
            "website": "cyclist-daily"
          }
        }
      ]
    }'

Verifying circulations

Let's verify that the document has been added to cyclist-daily. First, by calling the website endpoint:

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM/circulation/cyclist-daily

# RESPONSE
{
  "document_id": "ZHXE3Y6OJVAUFDJIM3M43AV5KM",
  "website_id": "cyclist-daily",
  "website_url": "/wheels-news/2019/09/04/parade",
  "website_primary_section": {
    "type": "reference",
    "referent": {
      "id": "/wheels-news",
      "type": "section",
      "website": "cyclist-daily"
    }
  },
  "website_sections": [
    {
      "type": "reference",
      "referent": {
        "id": "/wheels-news",
        "type": "section",
        "website": "cyclist-daily"
      }
    }
  ]
}

Then also by calling the generic endpoint (which lists all circulations across all websites):

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM/circulation

# RESPONSE
{
  "circulations": [
    {
      "document_id": "ZHXE3Y6OJVAUFDJIM3M43AV5KM",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/parade",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "id": "/news",
          "type": "section",
          "website": "river-city-post"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "id": "/news",
            "type": "section",
            "website": "river-city-post"
          }
        },
        {
          "type": "reference",
          "referent": {
            "id": "/the-city",
            "type": "section",
            "website": "river-city-post"
          }
        }
      ]
    },
    {
      "document_id": "ZHXE3Y6OJVAUFDJIM3M43AV5KM",
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/2019/09/04/parade",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "id": "/wheels-news",
          "type": "section",
          "website": "cyclist-daily"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "id": "/wheels-news",
            "type": "section",
            "website": "cyclist-daily"
          }
        }
      ]
    }
  ]
}

Publication

The document used in this guide was already published. As soon as the extra circulation is added, it becomes visible on the second website. It is also possible to add/update/delete circulations for an unpublished document. Those changes would take effect once the document is published.

Summing it up

In this short guide, you:

# Verified the document existed
GET https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM

# Listed all its circulations
GET https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM/circulation

# Added a new circulation, on a 2nd website
PUT https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM/circulation/cyclist-daily { ... }

# Verified it
GET https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM/circulation/cyclist-daily

# And double-checked the full list again
GET https://api.{{org}}.arcpublishing.com/draft/v1/story/ZHXE3Y6OJVAUFDJIM3M43AV5KM/circulation

In this section: