New Beta API: Page Update

Hot on the tails of the Page Recall API, we're excited to release the Page Update API to our Beta users.

This new endpoint allows you to:

• Append content to container elements such as div, table, and p
• Add, remove, and modify list items from lists
• Replace and remove text and image elements (img, h1...h6, p)

The following gist will walk you through issuing your first requests to the Page Update API. You can also test it out in our reference documentation's interactive console.

 

PATCH Actions

A request to the Page Update API consists of a PATCH request to the /pages/:id route. The body of the request should be a JSON array of PATCH actions, e.g.

 

[{
  "target": "#container",
  "action": "append",
  "position": "after",
  "content": "<img src='placecorgi.com/300' id='corgi'/>"
}]

 

Let's break down that PATCH Action:

• target: The element the action will target. Valid targets are any element with an Identifier.
  This uses the CSS selector syntax you know and love. For example, you would target an element such as <p id='foo'>bar</p> with "target": "#foo"
• action: The operation that will be carried out on the target. Valid actions are:
  • replace: Excise the element and all children from the HTML DOM, replace it with the content specified in content
  • append: Insert the HTML supplied in content as the last child of target
  • insert: Insert the HTML supplied in content as a sibling of target
• content: A string of Well-formed HTML to be inserted into the page as specified by the corresponding action.
• position: Usable only with insert and append actions. Used to specify that the insert or append action should insert content as a preceding sibling of target or as the first child of target, respectively.

A PATCH request must consist of at least one valid PATCH action. Multiple actions can be sent in a single request, like so:

[{
   "target": "#list",
   "action": "insert",
   "position": "before",
   "content": "<img src='placecorgi.com/300' id='corgi'/>"
 },
 {
   "target": "#list",
   "action": "append",
   "content": "<li>Item at the bottom of the list</li>"
 }]
 

Common Scenarios

Now you know how the API works, let's run through a few common scenarios:

1. Creating a Page with identifier-laden elements

   Creating a page uses the same POST /pages endpoint you've come to know and love, with one addition: you can now include the id parameter on an element so it can later be targeted for a PATCH operation.
   <img id='corgi' src='//placecorgi.com/300'/>
    

2. Replacing one of the page's elements.

   Let's take our corgi example above. Replacing that element with a new one – like an image of the OneNote logo – would look like:
   [{
   "target": "#corgi",
   "action": "replace",
   "content": "<img src='//onenotedev.github.io/images/header.png'
   id='onenote'/>"
   }]
    

3. Appending elements to the top and bottom of a container.

   This example demonstrates using multiple Actions in a single request and the usage of the optional position argument:
   [{
   "target": "#container",
   "action": "append",
   "position": "before",
   "content": "<img src='placecorgi.com/300' id='corgi'/>"
   },
   {
   "target": "#container",
   "action": "append",
   "content": "<p>Paragraph at the bottom of the target element</p>"
   }]
    

4. Updating the tags attached to a list item

   [{
   "target": "#todo-item-1",
   "action": "replace",
   "content": "<li id='todo-item-1' data-tag='to-do:completed'>ToDo Task</li>"
   }]
    

Go forth and PATCH

That should get you started with the Page Update API. We look forward to seeing what you do with it!

- Nick, on behalf of the OneNote API Team