(BETA) Get OneNote entities in one roundtrip using $expand

Update: $expand is now available in PROD. We’ve also updated our Android and iOS pickers to use this feature.

------------------------------------

Hi everyone! Jorge here. I'm excited to announce that we are shipping a new beta feature: $expand. $expand is part of the OData v4 standard and is a way of requesting related entities to be loaded inline in the response payload (e.g. sections inside notebooks). $expand lets you get more data in your API calls so you can avoid extra roundtrips.

Imagine you are displaying the user's notebooks and sections in a UI. To get those entities using the OneNote API without expand, you would need to:

1. Call GET https://www.onenote.com/api/v1.0/Notebooks
2. For each notebook returned, call https://www.onenote.com/api/v1.0/Notebooks/{NotebookId}/sections

With expand, you can simplify that logic into a single call! Notice how every notebook entity contains a section array with all the sections inside the notebook. Less API calls = Easier coding + Better performance.

// Get the user's Notebooks and all sections inside of them
GET www.onenote.com/api/beta/Notebooks?$expand=sections

    1: {
    2:    "@odata.context":"https://www.onenote.com/api/beta/$metadata#notebooks",
    3:    "value":[
    4:       {
    5:          "isDefault":true,
    6:          "userRole":"Owner",
    7:          "isShared":false,
    8:          "sectionsUrl":"https://www.onenote.com/api/beta/notebooks/0-2C1D0B837C428511!172/sections",
    9:          "sectionGroupsUrl":"https://www.onenote.com/api/beta/notebooks/0-2C1D0B837C428511!172/sectionGroups",
   10:          "links":{
   11:             "oneNoteClientUrl":{
   12:                "href":"onenote:https://d.docs.live.net/2c1d0b837c428511/Documents/My%20Notebook"
   13:             },
   14:             "oneNoteWebUrl":{
   15:                "href":"https://onedrive.live.com/redir.aspx?cid=2c1d0b837c428511&page=edit&resid=2C1D0B837C428511!172&parId=2C1D0B837C428511!135"
   16:             }
   17:          },
   18:          "name":"My Notebook",
   19:          "createdBy":"Someone",
   20:          "lastModifiedBy":"Someone",
   21:          "lastModifiedTime":"2014-02-13T22:04:40.44Z",
   22:          "id":"0-2C1D0B837C428511!172",
   23:          "self":"https://www.onenote.com/api/beta/notebooks/0-2C1D0B837C428511!172",
   24:          "createdTime":"2013-12-12T04:19:57.247Z",
   25:          "sections":[
   26:             {
   27:                "isDefault":false,
   28:                "pagesUrl":"https://www.onenote.com/api/beta/sections/0-2C1D0B837C428511!178/pages",
   29:                "name":"Quick Notes",
   30:                "createdBy":"Someone",
   31:                "lastModifiedBy":"Someone",
   32:                "lastModifiedTime":"2014-02-13T22:04:40.44Z",
   33:                "id":"0-2C1D0B837C428511!178",
   34:                "self":"https://www.onenote.com/api/beta/sections/0-2C1D0B837C428511!178",
   35:                "createdTime":"2013-12-17T02:47:49.603Z"
   36:             }
   37:          ]
   38:       },
   39:       {
   40:          "isDefault":false,
   41:          "userRole":"Owner",
   42:          "isShared":false,
   43:          "sectionsUrl":"https://www.onenote.com/api/beta/notebooks/0-2C1D0B837C428511!180/sections",
   44:          "sectionGroupsUrl":"https://www.onenote.com/api/beta/notebooks/0-2C1D0B837C428511!180/sectionGroups",
   45:          "links":{
   46:             "oneNoteClientUrl":{
   47:                "href":"onenote:https://d.docs.live.net/2c1d0b837c428511/Documents/This%20is%20the%20test%20notebook"
   48:             },
   49:             "oneNoteWebUrl":{
   50:                "href":"https://onedrive.live.com/redir.aspx?cid=2c1d0b837c428511&page=edit&resid=2C1D0B837C428511!180&parId=2C1D0B837C428511!135"
   51:             }
   52:          },
   53:          "name":"This is the test notebook",
   54:          "createdBy":"Someone",
   55:          "lastModifiedBy":"Someone",
   56:          "lastModifiedTime":"2014-06-11T20:32:40.27Z",
   57:          "id":"0-2C1D0B837C428511!180",
   58:          "self":"https://www.onenote.com/api/beta/notebooks/0-2C1D0B837C428511!180",
   59:          "createdTime":"2014-06-11T20:16:11.807Z",
   60:          "sections":[
   61:             {
   62:                "isDefault":false,
   63:                "pagesUrl":"https://www.onenote.com/api/beta/sections/0-2C1D0B837C428511!183/pages",
   64:                "name":"Top level section",
   65:                "createdBy":"Someone",
   66:                "lastModifiedBy":"Someone",
   67:                "lastModifiedTime":"2014-06-11T20:16:39.553Z",
   68:                "id":"0-2C1D0B837C428511!183",
   69:                "self":"https://www.onenote.com/api/beta/sections/0-2C1D0B837C428511!183",
   70:                "createdTime":"2014-06-11T20:16:27.207Z"
   71:             }
   72:          ]
   73:       }
   74:    ]
   75: }

But wait, there's more! You can also expand other properties on other entities:

// Get the user's notebooks with all sections and sectionGroups (with their sections too)

GET www.onenote.com/api/beta/Notebooks?$expand=sections,sectionGroups($expand=sections)

// For a known section with id 0-2C1D0B837C428511!172, get its parent Notebook.

GET www.onenote.com/api/beta/Sections/0-2C1D0B837C428511!172?$expand=parentNotebook

// For a known notebook with id 0-2C1D0B837C428511!178, expand all sections and sectionGroups

GET www.onenote.com/api/beta/Notebooks/0-2C1D0B837C428511!172?$expand=sections,sectionGroups($expand=sections)

// (*magic*) Use $levels for a recursive $expand that gives you the whole OneNote hierarchy (all notebooks, sections, and section groups)

GET www.onenote.com/api/beta/Notebooks?$expand=sections,sectionGroups($expand=sections,sectionGroups($levels=max;$expand=sections))

Here's a quick list showing what you can expand in all of our GET endpoints:

When we ship this to PROD, we'll update our iOS picker and Android picker to take advantage of this new feature. Give it a try, and feel free to ping us here or on twitter @onenotedev. Happy expanding!

Jorge