Publishing Workflow

The Live Editor API requires that you to save changes to content records as drafts and publish them later. Following is the process and considerations when using the API to manage content.

Drafts

Drafts in Live Editor allow you to create, update, and delete content without publishing the changes to the live website yet.

Drafted data then can be loaded via the Drafts resource or side-loaded along with the drafted resource itself.

Saving drafts of data

The Live Editor API saves all of your changes to draftable resources as drafts, including create, update, and delete operations.

If you want to publish changes immediately, you must instruct the API to do so after saving the draft(s). See the Publishing section below for details on how to do that.

Draftable resources

The following resources are draftable:

Loading drafted data

When you load a resource from the Live Editor API, it will by default return the live, published version of the data.

To load the drafted version of the data, include the draft relationship in the request URL: 

https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc?include=draft

The body of the response will contain the draft record in the includes section of the response, and drafted changes will be loaded directly into the data attributes section as well.

To help illustrate, here is an example without the draft loaded:

Request 

      GET https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc HTTP/1.1
      Accept: application/vnd.api+json

Response 

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "type": "pages",
          "id": "254fbed6-9cbb-47db-88b4-8e1c0b67a2dc",
          "links": {
            "self": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc"
          },
          "attributes": {
            "page-type": "page",
            "path": "/donuts_and_pastries",
            "title": "Donuts and Pastries",
            "description": null,
            "keywords": null,
            "search-engine-indexable": true,
            "search-engine-followable": true,
            "canonical-url": null,
            "published-at": "2012-04-23T18:25:43.511Z",
            "trashed-at": "2012-04-23T18:25:43.511Z",
            "created-at": "2012-04-23T18:25:43.511Z",
            "updated-at": "2012-04-23T18:25:43.511Z"
          },
          "relationships": {
            "parent": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/relationships/parent"
                "related": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/parent"
              },
              "data": {
                "type": "pages",
                "id": "14d8901c-62ab-485e-a307-9225aa011257"
              }
            },
            "layout": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/relationships/layout"
                "related": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/layout"
              },
              "data": {
                "type": "layouts",
                "id": "c782d600-5eb4-49dc-85c3-6186bb2d6b47"
              }
            },
            "draft": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/relationships/draft"
                "related": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/draft"
              },
              "data": {
                "type": "drafts",
                "id": "899dbea8-32f2-4096-abdf-9755739a6d65"
              }
            }
          }
        }
      }

And here is an example with the draft included:

Request 

      GET https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc?include=draft HTTP/1.1
      Accept: application/vnd.api+json

Response 

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "type": "pages",
          "id": "254fbed6-9cbb-47db-88b4-8e1c0b67a2dc",
          "links": {
            "self": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc"
          },
          "attributes": {
            "page-type": "page",
            "path": "/donuts-and-pastries",
            "title": "Donuts and Pastries - Coffee Shop",
            "description": null,
            "keywords": null,
            "search-engine-indexable": true,
            "search-engine-followable": true,
            "canonical-url": null,
            "published-at": "2012-04-23T18:25:43.511Z",
            "trashed-at": "2012-04-23T18:25:43.511Z",
            "created-at": "2012-04-23T18:25:43.511Z",
            "updated-at": "2012-04-23T18:25:43.511Z"
          },
          "relationships": {
            "parent": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/relationships/parent"
                "related": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/parent"
              },
              "data": {
                "type": "pages",
                "id": "14d8901c-62ab-485e-a307-9225aa011257"
              }
            },
            "layout": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/relationships/layout"
                "related": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/layout"
              },
              "data": {
                "type": "layouts",
                "id": "c782d600-5eb4-49dc-85c3-6186bb2d6b47"
              }
            },
            "draft": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/relationships/draft"
                "related": "https://coffee.api.liveeditorapp.com/pages/254fbed6-9cbb-47db-88b4-8e1c0b67a2dc/draft"
              },
              "data": {
                "type": "drafts",
                "id": "899dbea8-32f2-4096-abdf-9755739a6d65"
              }
            }
          }
        },
        "included": [
          {
            "type": "drafts",
            "id": "899dbea8-32f2-4096-abdf-9755739a6d65",
            "links" {
              "self": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65"
            },
            "attributes": {
              "event": "update",
              "object-changes": {
                "path": [
                  "/donuts_and_pastries",
                  "/donuts-and-pastries"
                ],
                "title": [
                  "Donuts and Pastries",
                  "Donuts and Pastries - Coffee Shop"
                ]
              },
              "created-at": "2012-04-23T18:25:43.511Z",
              "updated-at": "2012-04-23T18:25:43.511Z"
            },
            "relationships": {
              "item": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/relationships/item"
                  "related": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/item"
                },
                "data": {
                  "type": "pages",
                  "id": "254fbed6-9cbb-47db-88b4-8e1c0b67a2dc"
                }
              },
              "user": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/relationships/user"
                  "related": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/user"
                },
                "data": {
                  "type": "users",
                  "id": "968b3464-fc8a-4b49-8ac9-728f43e59e23"
                }
              },
              "publication-dependencies": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/relationships/publication-dependencies"
                  "related": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/publication-dependencies"
                }
              },
              "reversion-dependencies": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/relationships/reversion-dependencies"
                  "related": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/reversion-dependencies"
                }
              },
              "hyperlinks": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/relationships/hyperlinks"
                  "related": "https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65/hyperlinks"
                }
              }
            }
          }
        ]
      }

Notice that the drafted path and title values are loaded into the main record, so the main point of including the draft is to see the drafted item’s state before the drafted changes were applied.

Discarding drafts

After a draft has been created, you have the option of reverting it and putting the drafted item back in its original state (or deleting the item altogether if the draft was for a new piece of content).

To revert a draft, issue a DELETE request to its record at the drafts API endpoint:

Request 

      DELETE https://coffee.api.liveeditorapp.com/drafts/899dbea8-32f2-4096-abdf-9755739a6d65
      Accept: application/vnd.api+json

Response 

      204 No Content

Publishing

After a draft has been created, you then have the option of publishing the content to the live version of the website. This is done by POSTing to the revisions API endpoint.

This example demonstrates creating a revision with a commit log and requesting that 3 draft records be published as part of the revision:

The API will respond with the generated revision.

Request 

      POST /revisions HTTP/1.1
      Accept: application/vnd.api+json
      
      {
        "data": {
          "type": "revisions",
          "attributes": {
            "comments": "This is a commit log for the revision."
          },
          "relationships": {
            "drafts": {
              "data": [
                {
                  "type": "drafts",
                  "id": "899dbea8-32f2-4096-abdf-9755739a6d65"
                },
                {
                  "type": "drafts",
                  "id": "c89fa591-4715-4e2b-9358-535348b4958b"
                },
                {
                  "type": "drafts",
                  "id": "0762311d-a11b-4825-bed8-3b464d1f4957"
                }
              ]
            }
          }
        }
      }

Response 

      HTTP/1.1 201 Created
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "type": "revisions",
          "id": "4be1f9e0-32d9-4aff-82a3-2011aa57797d",
          "links": {
            "self": "https://coffee.api.liveeditorapp.com/revisions/4be1f9e0-32d9-4aff-82a3-2011aa57797d"
          },
          "attributes": {
            "comments": "This is a commit log for the revision.",
            "versions-count": 3,
            "created-at": "2012-04-23T18:25:43.511Z"
          },
          "relationships": {
            "user": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/revisions/4be1f9e0-32d9-4aff-82a3-2011aa57797d/relationships/user"
                "related": "http://coffee.api.liveditorapp.com/revisions/4be1f9e0-32d9-4aff-82a3-2011aa57797d/user"
              }
              "data": {
                "id": "dc8b2b71-47f3-4702-9f85-d0822873ee83",
                "type": "users"
              }
            },
            "versions": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/revisions/4be1f9e0-32d9-4aff-82a3-2011aa57797d/relationships/versions",
                "related": "https://coffee.api.liveeditorapp.com/revisions/43dfb73a-cf08-420e-9813-1cd99a5b743b/versions"
              }
            },
            "drafts": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/revisions/4be1f9e0-32d9-4aff-82a3-2011aa57797d/relationships/drafts"
                "related": "https://coffee.api.liveeditorapp.com/revisions/4be1f9e0-32d9-4aff-82a3-2011aa57797d/drafts"
              }
            }
          }
        }
      }

Protip: If you issue ?include=versions in the URL along with the POST, the API will also include the revision’s related versions.

Publication, reversion, and hyperlink dependencies

When you publish a draft, sometimes that will trigger the publishing of another related draft along with it. For example, when a content item is deleted, its related content blocks will be deleted along with it.

When working with drafts, there are a couple relationships to help you know what’s going to happen ahead of time:

publication-dependencies
Drafts that will be force-published along with publication of this draft.
reversion-dependencies
Drafts that will be force-reverted along with reversion/discarding of this draft.

Another thing to consider before publishing or reverting a draft is the hyperlinks relationship. This indicates whether or not other content is linking to this draft. So if you want to delete this content, for example, this will let you know ahead of time if you’re going to break some links on the site.

You can code your client to examine these 3 relationships to let them know ahead of time what will happen when publishing or reverting drafts. As with all JSON API-based endpoints in Live Editor, you can issue an include query parameter along with the request for drafts, requesting that the relationships be side-loaded along with the response:

Request 

      GET /drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6?include=publication-dependencies,reversion-dependencies,hyperlinks HTTP/1.1
      Accept: application/vnd.api+json

Response 

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "type": "drafts",
          "id": "da12f027-8b89-430b-a5c9-8ca6ba855bb6",
          "links": {
            "self": "https://coffee.api.liveeditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6"
          },
          "attributes": {
            "event": "create",
            "object-changes": [
              "asset-id": [
                "e53c8ba4-f988-490e-89da-403cd83a70da",
                "abe9fb9b-8d8a-4199-8680-57463ea0cbc7"
              ]
            ],
            "created-at": "2012-04-23T18:25:43.511Z",
            "updated-at": "2012-04-23T18:25:43.511Z"
          },
          "relationships": {
            "item": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/relationships/item",
                "related": "http://coffee.api.liveditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/item"
              },
              "data": {
                "type": "content-blocks",
                "id": "d23f9ee5-60f2-4a39-ad94-326aece84112"
              }
            },
            "user": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/relationships/user",
                "related": "http://coffee.api.liveditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/user"
              },
              "data": {
                "type": "users",
                "id": "c9b971a9-d3a4-455a-a3a4-7324e93253cc"
              }
            },
            "publication-dependencies": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/relationships/publication-dependencies",
                "related": "http://coffee.api.liveditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/publication-dependencies"
              },
              "data": [
                {
                  "type": "drafts",
                  "id": "b1e43f62-7ebd-44a8-8460-68e8b4011b0b"
                }
              ]
            },
            "reversion-dependencies": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/relationships/reversion-dependencies",
                "related": "http://coffee.api.liveditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/reversion-dependencies"
              },
              "data": []
            },
            "hyperlinks": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/relationships/hyperlinks",
                "related": "http://coffee.api.liveditorapp.com/drafts/da12f027-8b89-430b-a5c9-8ca6ba855bb6/hyperlinks"
              },
              "data": []
            }
          }
        },
        "included": [
          {
            "type": "drafts",
            "id": "b1e43f62-7ebd-44a8-8460-68e8b4011b0b",
            "links": {
              "self": "https://coffee.api.liveeditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b"
            },
            "attributes": {
              "event": "create",
              "object-changes": {},
              "created-at": "2012-04-23T18:25:43.511Z",
              "updated-at": "2012-04-23T18:25:43.511Z"
            },
            "relationships" {
              "item": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/relationships/item",
                  "related": "http://coffee.api.liveditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/item"
                },
                "data": {
                  "type": "contents",
                  "id": "a01fa21d-41d5-404e-9599-1cd003650272"
                }
              },
              "user": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/relationships/user",
                  "related": "http://coffee.api.liveditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/user"
                },
                "data": {
                  "type": "users",
                  "id": "c9b971a9-d3a4-455a-a3a4-7324e93253cc"
                }
              },
              "publication-dependencies": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/relationships/publication-dependencies",
                  "related": "http://coffee.api.liveditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/publication-dependencies"
                },
                "data": []
              },
              "reversion-dependencies": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/relationships/reversion-dependencies",
                  "related": "http://coffee.api.liveditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/reversion-dependencies"
                },
                "data": [
                  {
                    "type": "drafts",
                    "id": "da12f027-8b89-430b-a5c9-8ca6ba855bb6"
                  }
                ]
              },
              "hyperlinks": {
                "links": {
                  "self": "https://coffee.api.liveeditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/relationships/hyperlinks",
                  "related": "http://coffee.api.liveditorapp.com/drafts/b1e43f62-7ebd-44a8-8460-68e8b4011b0b/hyperlinks"
                },
                "data": []
              }
            }
          }
        ]
      }

In the example above, this draft for a content block has no reversion dependencies or hyperlinks, but it has a publication dependency on its related content item’s draft. If you were to publish this draft only, its related content item would also be automatically published.

Related