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