(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
// (*magic*) Use $levels for a recursive $expand that gives you the whole OneNote hierarchy (all notebooks, sections, and section groups)
Here's a quick list showing what you can expand in all of our GET endpoints:
| Entity | Can be expanded on… |
| Notebook | sections, sectionGroups |
| Section | parentNotebook, parentSectionGroup |
| Section Group | sections, sectionGroups, parentNotebook, parentSectionGroup |
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