An Update to Page Update

A few months ago we announced the Page Update API beta. Thanks to feedback, we've made a few changes to give you greater precision when making updates to pages. Read on for details.

As before, the PATCH endpoint, /api/beta/pages/{page-id}/content, allows you to add, remove, and update content on a OneNote page.

What's Different

The two major change are the addition of includeIDs, which allows you to precisely target elements on the page and the introduction of the data-id parameter.

 

Everything else about constructing PATCH requests is the same as before – don't worry: if this is new to you, we've got a recap at the end of the post.

 

includeIDs

The OneNote API generates IDs for all elements on a page that can be updated. To get generated IDs, include the query parameter ?includeIDs=true in your request to get page content: GET …/api/beta/pages/{page-id}/content?includeIDs=true

Elements that can be used as a target for updates will include an id attribute:

 

<p id="p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}">Some text on the page</p>

 

<img id="img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}" ... />

To target an element via its id property, use the following syntax:

 

"target": "img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}"

 

data-id

Rather than using the id attribute to attach a fixed identifier to elements, you must now use the data-id attribute:

<img id='corgi' src='//placecorgi.com/300'/> should now be <img data-id='corgi' src='//placecorgi.com/300'/>

 

Any element can have a data-id, but to use the 'replace' action, you must use the id attribute generated by includeIDs.

 

Update Objects: Recap

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

[{

  "target": "body",

  "action": "append",

  "position": "before",

  "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 body, object and img tags with data-id, any element with an id attribute created via includeIDs

    This uses the CSS selector syntax you know and love. For example, you would target an element such as <img data-id='foo' src="…"/> with "target": "#foo"
    Likewise, an element with id would use "target": "img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}"

  • 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 the following 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.

 

This directive reverses the positioning sense of the append or insert actions.  For append, it switches the insert to place the content as the first child of target.  For insert, it switches the insert to place the content as a preceding sibling of target.

 

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

 

[{

   "target": "body",

   "action": "append",

   "position": "before",

   "content": "<img src='placecorgi.com/300' id='corgi'/>"

 },

 {

   "target": "body",

   "action": "append",

   "content": "<p>Text at the bottom of the page</p>"

 }]

 

Go forth and PATCH

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

- Nick, on behalf of the OneNote API Team