Share via

Notebook Hierarchy Recall Preview

  • Article

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:

HTTP Method

Endpoint

What it will return

GET

~/Notebooks

List of all notebooks & data

GET

~/Notebooks/<id>

Data for a specific notebook

GET

~/Notebooks/<id>/Sections

List of all top-level sections & data for a given notebook

GET

~/Notebooks/<id>/SectionGroups

List of all top-level section groups & data for a given notebook

GET

~/Sections

List of all sections across all notebooks

GET

~/Sections/<id>

Data for a specific section

GET

~/SectionGroups

List of all section groups across all notebooks

GET

~/SectionGroups/<id>

Data for a specific section group

GET

~/SectionGroups/<id>/Sections

List of all sections & data under a given section group

GET

~/SectionGroups/<id>/SectionGroups

List of all section groups & data under a given section group

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.

Comments

  • Anonymous
    May 02, 2014
    Thanks for this preview. Can we rely on the IDs of the pages/sections remaining constant? So, for example, if a user moves a section or page will the GUID stay the same or will it change (like it does when using the COM api) Cheers db

  • Anonymous
    May 04, 2014
    @Darren - Yup, that's exactly the idea. The ID will be a permanent/unique ID regardless of if a user moves or renames a notebook/section/page.

  • Anonymous
    May 15, 2014
    Sounds good, thanks.   Will the page/subpage hierarchy be exposed as well.

  • Anonymous
    May 16, 2014
    @Burt - Right now this is being built to support creating pages in specific locations, so no ability to expose Pages just yet. However, as shown in our roadmap post, we are quickly working on APIs to allow you to update and recall pages, so once we have that, we will certainly add the ability to expose the pages as part of the hierarchy. Right now there are no plans to expose the pages/subpage hierarchy itself. However, if this is something your interested in, can you please suggest it at onenotedev.uservoice.com

  • Anonymous
    July 17, 2014
    I haven't been able to make the $expand option work for anything I've tried. Can you post an example please?

  • Anonymous
    July 18, 2014
    @Don - Sorry about that. We've been having issues with the $expand feature so we haven't turned it on yet. I just turned it on in our BETA endpoint so you should be able to use it there. Hoping to be able to turn it on in production in a few weeks. Would love to get any feedback or bugs that you have from trying it on the BETA endpoint

  • Anonymous
    July 18, 2014
    I've tried www.onenote.com/.../pages$expand and www.onenote.com/.../notebooks$expand. Both of them return a 500 error. What is the correct syntax?

  • Anonymous
    July 18, 2014
    Sorry. Typo in my post. Both failing urls are in the beta endpoint and end with ?$expand.

  • Anonymous
    July 18, 2014
    @Don - $expand is used to expand a Navigation Property (i.e. Section or Section Group under a notebook). For example, the following call should work: www.onenote.com/.../notebooks$expand=sections (In your call, you were also missing the '?' delimiter). For more information on how $expand works, check out the OData specification on it: docs.oasis-open.org/.../odata-v4.0-os-part2-url-conventions.html

  • Anonymous
    July 18, 2014
    Thanks. That answers my question. I actually had the ? in my query, but I didn't specify what to expand. Now I'm looking for a single request that returns all Notebooks, Section Groups, Sections, and Pages. I'm getting the first three. I'll keep looking for a way to include pages in what gets expanded.

  • Anonymous
    July 18, 2014
    @Don - Great! Pages should be working in a few days. It's one of the things we just fixed in our code. To get everything, you would need to make a call like: www.onenote.com/.../notebooks$expand=sections($expand=pages),sectionGroups($expand=sections($expand=pages),sectionGroups) One of the limitations of our API is that there's no way to expand the sections/pages under each Section Group without manually writing out the expand for each level. The example above would show you all Notebooks, top-level sections and pages in them, as well as the top-level section groups and sections/pages under the top-level section groups. We're looking at writing a custom OData function to support getting everything as we see this as a valuable scenario.

  • Anonymous
    May 23, 2015
    My primary wish is that subpages can take the name of the primary page. Currently I scan a document and I might get a 50 page document called printout. I rename the first page to ABC but the following 49 pages will be page 2, page 3..etc. I want the ability somehow to have the sub pages called ABC - Page 2, ABC Page 3 etc...