How to Decirculate a Document in Draft API

The purpose of this guide is to demonstrate how to use the Draft API to decirculate a document from a website and recirculate it back to the same website.

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 back to The Introductory Guide.

Existing document

Given a circulated document, URWCJIIJPNGEZKZR3EZ54TO22Y, start by listing the active circulations.

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"
          }
        }
      ]
    }
  ]
}

Additionally, list redirects for both circulated websites.

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

# RESPONSE
{
  "redirects": [
    {
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/2019/09/03/parade",
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "created_at": "2019-09-04T12:13:34.91Z",
      "updated_at": "2019-09-04T12:21:06.22Z"
    }
  ]
}

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

# RESPONSE
{
  "redirects": []
}

These calls provide the following information:

The document is circulated on website river-city-post at URL /news/2019/09/04/parade.
The document is circulated on website cyclist-daily at URL /wheels-news/2019/09/04/parade.
URL /wheels-news/2019/09/03/parade on cyclist-daily redirects to the document's circulation URL, /wheels-news/2019/09/04/parade.

Decirculating a document from a website

To remove document URWCJIIJ... from website cyclist-daily, call the de-circulate endpoint.

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

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

Listing circulation again now shows only one circulated website on which URWCJIIJ... will appear.

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": "river-city-post",
      "website_url": "/news/2019/09/04/parade",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/news",
          "website": "cyclist-daily"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/news",
            "website": "cyclist-daily"
          }
        }
      ]
    }
  ]
}

Note

Redirects to the document on the decirculated cyclist-daily website WILL NOT be removed, continuing to redirect to the now missing /news/2019/09/04/parade circulation URL. This preservation enables re-use in the event of recirculation to cyclist-daily. The preserved redirect can be verified by a direct fetch after decirculation.

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/redirect/cyclist-daily/wheels-news/2019/09/03/parade"

# RESPONSE
{
  "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
  "website_id": "cyclist-daily",
  "website_url": "/wheels-news/2019/09/03/parade",
  "created_at": "2019-09-04T12:13:34.91Z",
  "updated_at": "2019-09-04T12:21:06.22Z"  
}

Recirculating a document to a website

Adding a document back to a website is identical to a first-time circulate. If website_url is omitted, the URL will be automatically generated. In this case, URWCJIIJ... is recirculated to website cyclist-daily with the prior URL explicitly specified.

curl --request PUT \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'content-type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/circulation/cyclist-daily \
  --data '{
    "website_url": "/wheels-news/2019/09/04/parade"
  }'

# RESPONSE
{
  "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
  "website_id": "cyclist-daily",
  "website_url": "/wheels-news/2019/09/04/parade"
}

Listing the document's circulation a final time shows cyclist-daily back as one of the document's active websites. Redirects preserved across decirculation will now point to the present document.

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"
    },
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/parade"
    }
  ]
}

In this section: