Notebook Hierarchy Recall Preview

We are hard at work lighting up the features listed on our roadmap that we shared with you here. As is clear from the feedback on our API feedback site, enabling the ability to create notes in specific sections and notebooks is very important.

Before we can enable this, a critical component is exposing APIs to recall a list of a user's notebooks and the notebook hierarchy so that they can select which section they want to create a page in. Today, I want to share with you something we are working on currently; how we will expose this "hierarchy recall" to enable developers to expose a list of notebooks and sections to users. I should be clear that once we expose this work, creating pages in a specific section should follow pretty quickly.

As previously mentioned in a blog post here, OneNote notebooks have a hierarchy that looks like:

Notebooks >> Section Group (optional) >> Section >> Page

where a Section Group can contain other Section Groups.

We will expose this through a similar list of API endpoints:

We'll return this data using the OData Version 4.0 specification. Here is an example of what the response would look like for a GET ~/Notebooks/<id> call:

  { 
 "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Notebooks/$entity",

 "id": "<Unique Notebook Identifier>", //Unique ID for the notebook that can be used for future identification

 "isDefault": "<true/false>", //Identifies whether or not this is the default notebook for the user

 "name": "Notebook Title", //Name of the notebook that user sees

 "userRole": "<"Owner", "Contributor", "Reader">", //Specifies the access permissions that the user has

 "creationDate": "<datetime>", //The date & time that the notebook was created

 "ownerName": "John Doe", //The name of the user who owns the notebook

 "shared": "<true/false>", //Whether or not other users can see the content in the notebook

 "modifiedDate": "<datetime>", //The date & time that any page or section in the notebook was last changed

 "lastModifierName": "Jane Doe",//The name of the user who last changed a page or section in the notebook

 "links":{
 "self": {"href": "https://www.onenote.com/api/v1.0/notebooks/<Unique Notebook Identifier>"},
 "oneNoteWebUrl": {"href": "<URL to open in OneNote Online>"},
 "oneNoteClientUrl": {"href": "<URL to open in OneNote client>"},
 "sectionsUrl": { "href": "https://www.onenote.com/api/v1.0/notebooks/<Unique Notebook Identifier>/sections"},
 "sectionGroupsUrl": {"href": "https://www.onenote.com/api/v1.0/notebooks/<Unique Notebook Identifier>/sectionGroups"} 
 } 

}

In addition we will support the following query parameters:

• $orderBy - name, modifiedDate, creationDate (asc/desc):

This will allow you to specify the order you want each of the elements returned in

• $expand

We will also support the $expand query term. The expand query will allow you to get all of the hierarchy information (i.e. all notebooks/sections/section groups for a user) back in one roundtrip call. Of course the information returned with this option will come in a larger data packet and take longer to process than the making one of the individual calls, but we know that there are different scenarios where choosing to use this query term may or may not be useful to you.

It's important to note - we are still implementing this, so a few of the specific values mentioned above may change when we release it. We'll make sure to post full documentation on the features when we release and you should use that for a reference rather than this post.

Using the endpoints and data defined here, you should be able to build a "picker" for your users where they can select a specific section for you to create a page in. We are aiming to have this work done in the next 1-2 months. If you have any feedback on any of the information here, please share it with us in the comments here or @OneNoteDev. We'd love to hear your feedback to ensure we implement this in a way that works for you and makes sense.