Draft API Interactions with ANS

Overview

The Draft API document endpoints listed below contain some special handling for the ANS blob that is passed in through the request body and/or returned in responses. When creating and editing Revisions, there are some fields that are promoted to “first-class” fields in order to make searching and JSON manipulation easier, while others are handled in separated endpoints entirely.

This document outlines the various ways that ANS fields are handled and what users can expect when making requests.

For this documentation, we will be referring to the following endpoints:

POST /draft/v1/story: Create a Document

GET /draft/v1/story/:id/revision: List All Revisions

GET /draft/v1/story/:id/revision/:revision_id: Get Revision by ID

PUT /draft/v1/story/:id/revision/draft: Update Draft Revision

POST /draft/v1/story/:id/revision/published: Publish Document

DELETE /draft/v1/story/:id/revision/published: Unpublish Document

PUT /draft/v1/story/:id/revision/revert: Revert Document

Each of the fields discussed below is nested under the ans field, which is a property of a revision.

Dates

System Generated Fields

• created_date
• last_updated_date
• first_publish_date

These fields are generated by the system, and will be ignored if they are passed into Write endpoints through the request body.

Overridable Fields

• publish_date
• display_date

These fields are generated by the system, but can be overridden by values in the request body when using the following two endpoints:

• POST /draft/v1/story: Create a Document
• PUT /draft/v1/story/:id/revision/draft: Update Draft Revision

See our Guide for Manually Setting the Publish_date or Display_date of a Document

Revert Document Endpoint

The fields first_publish_date and publish_date are omitted from the response of this endpoint.

IDs

The following fields are omitted from responses. They will be ignored if they are included in the request body.

• _id
• revision.revision_id
• revision.parent_id

URLs and Circulations

In Draft API, the concept of a Document’s Revisions is independent of its Circulations. For this reason, we no longer return Circulation information in the Revision endpoints. To access these fields, you can see the Circulation endpoints, which are documented here.

The following fields are omitted from responses. Draft API endpoints will reject requests if any of these fields are present in the request body.

• websites
• canonical_url
• taxonomy.sections
• taxonomy.sites
• taxonomy.primary_section
• taxonomy.primary_site

Revisions

The following fields are omitted from responses. They will be ignored if they are included in the request body.

• revision.index
• revision.branch
• revision.editions

List all Revisions Endpoint

The following fields are omitted from the response from this endpoint in order to remain compatible with Story API. In later versions of Draft API after the full Deprecation of Story API, we will begin to send these additional fields.

• canonical_website
• owner.id
• version
• slug