Revisions endpoint changes in upgraded version

Arc XP is rolling out Draft API updates to customers that will enable new functionality in the API and we’ve taken steps to ensure that the upgrades to your environments are seamless without any impact on your operations. For this reason, you may not have noticed this upgrade happening unless you received a scheduled maintenance email from Arc XP. However, the upgraded version of Draft API includes a few non-breaking changes to the Draft API customer-facing interface, which this article explains. 

Changes to the Revisions endpoint

Calls to the /draft/v1/{type}/{id}/revision endpoint will return all story fields for each revision. Previously, the response only contained a subset of story fields for each revision. The changes are non-breaking and are limited to the API’s response. The changes include:

• The upgraded version’s API response body contains additional fields than existed in the legacy version.
• The additional fields are nested under the ans parent field.
• All of the fields previously returned remain in the upgraded response.
• The overall JSON structure of the API response body has not changed except for the additional nested fields.
• The additional fields create only a slight increase (<1KB on average) in the data footprint of the JSON response, per revision object.

Code Examples

The following code samples compare legacy and upgraded API responses to the /revision endpoint of Draft API. Note that the code examples have been reduced to only the ans key within the entire JSON document for the sake of readability.

Legacy API response

"ans":{
   "additional_properties":{
      "has_published_copy":false
   },
   "canonical_website":"test_website",
   "created_date":"2022-12-30T22:20:28.962Z",
   "headlines":{
      "basic":"This is a test headline"
   },
   "last_updated_date":"2022-12-30T22:20:28.962Z",
   "owner":{
      "id":"org123",
      "sponsored":false
   },
   "revision":{
      "branch":"default",
      "index":1,
      "published":false,
      "revision_id":"YFY5ILIIABCC5OLWOLP6PRYOJI"
   },
   "type":"story"
}

Upgraded API response

"ans":{
   "additional_properties":{
      "has_published_copy":true,
      "is_published":true,
      "sha1":"hidden_sha1_value_goes_here"
   },
   "canonical_website":"test_website",
   "created_date":"2022-12-30T22:20:29.322Z",
   "credits":{
      "by":[
         {
            "name":"Jane Doe",
            "type":"author"
         }
      ]
   },
   "description":{
      "basic":"This is a test headline"
   },
   "display_date":"2022-12-30T22:18:19Z",
   "distributor":{
      "mode":"reference",
      "reference_id":"2573309d-6de2-421d-8fbe-66ccff156fd4"
   },
   "first_publish_date":"2022-12-30T22:20:30.486Z",
   "headlines":{
      "basic":"This is a test headline"
   },
   "label":{
      "overline":{
         "text":"Int. Football"
      }
   },
   "last_updated_date":"2022-12-30T22:20:30.48Z",
   "owner":{
      "id":"sandbox.org",
      "sponsored":false
   },
   "promo_items":{
      "basic":{
         "_id":"SN4UA45VBRQTRVKORFJRLTP6SE",
         "referent":{
            "id":"SN4UA45VBRQTRVKORFJRLTP6SE",
            "referent_properties":{
               "caption":"This is a test caption",
               "originalName":"this-is-a-test-name",
               "originalUrl":"https://images.abcd.com/v1/photos/raw/ster-engd-mch-15-ciano-rdo-of-manr-uned-lks-on-duri/lrge"
            },
            "type":"image"
         },
         "type":"reference"
      }
   },
   "publish_date":"2022-12-30T22:20:30.486Z",
   "revision":{
      "branch":"default",
      "editions":[
         "default"
      ],
      "index":4,
      "parent_id":"DU2OGIMF5JF7RNBOLQ22V55U3Y",
      "published":true,
      "revision_id":"OINUBQEWCZGOLMLA2JGVKYCPRM"
   },
   "source":{
      "name":"Spoer",
      "source_id":"https://www.spzzer.du/ael/ciano-ldo-von-sstarai-aben-traer-reaonen/",
      "source_type":"other",
      "system":"arc i/o"
   },
   "subheadlines":{
      "basic":"Some headline goes here"
   },
   "taxonomy":{
      "tags":[
         {
            "description":"Sporter",
            "slug":"sporzer",
            "text":"Sporzer"
         },
         {
            "slug":"mancter-ed-fc",
            "text":"Master Ud F"
         },
         {
            "slug":"redaktikchland",
            "text":"Redtzwerk Dela"
         },
         {
            "slug":"torm-ru-um-die-welt",
            "text":"Tolarmnd um die lt"
         },
         {
            "slug":"tews",
            "text":"Tops"
         },
         {
            "slug":"fu-ll-inteional",
            "text":"ll Intonal"
         }
      ]
   },
   "type":"story",
   "version":"0.10.7"
}