{"id":1270,"date":"2017-07-21T21:59:51","date_gmt":"2017-07-22T04:59:51","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=1270"},"modified":"2021-10-18T13:22:25","modified_gmt":"2021-10-18T20:22:25","slug":"a-few-performance-tips-for-using-the-onenote-api","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/a-few-performance-tips-for-using-the-onenote-api\/","title":{"rendered":"A few performance tips for using the OneNote API"},"content":{"rendered":"

Hello world,<\/p>\n

In StackOverflow and twitter, we often hear questions on how to make queries to the API faster. Here are a few recommendations:<\/p>\n

Always log the “X-CorrelationId”, “Date” and “Request-Processing-Time” headers on the OneNote API response<\/h3>\n

First – make sure you have the API’s performance-related information logged. All requests to the OneNote API have those 3 headers – here’s an example:<\/p>\n

HTTP\/1.1 200 OK\nCache-Control: no-cache\nPragma: no-cache\nContent-Type: application\/xml\nExpires: -1\nServer: Microsoft-IIS\/10.0\nX-CorrelationId: d0ff1746-6b9d-456f-ae18-3c7bc822d53e<\/strong>\nX-UserSessionId: d0ff1746-6b9d-456f-ae18-3c7bc822d53e\nX-OfficeFE: deployment29(8).MSOffice.ClassNotebookApiSingleBox_IN_0\nX-OfficeVersion: 16.0.8418.3004\nX-OfficeCluster: localhost\nP3P: CP=\"CAO DSP COR ADMa DEV CONi TELi CUR PSA PSD TAI IVDi OUR SAMi BUS DEM NAV STA UNI COM INT PHY ONL FIN PUR\"\nX-Content-Type-Options: nosniff\nRequest-Processing-Time: 838.9842 ms<\/strong>\nOData-Version: 4.0\nX-AspNet-Version: 4.0.30319\nX-Powered-By: ASP.NET\nDate: Fri, 28 Jul 2017 16:54:58 GMT<\/strong>\nContent-Length: 32552<\/pre>\n
X-CorrelationId: This uniquely identifies any API request. In case there are any issues with\u00a0the API, we can use this for debugging.\nRequest-Processing-Time: Latency of the API.\nDate: The date when the request was made.<\/p>\n
Having this in your logs will make debugging performance issues easier.<\/p>\n
Use $select to select the minimum set of properties you need<\/h3>\n
When querying for a resource (say for example, sections inside a notebook), you make a request like:<\/p>\n
GET ~\/notebooks\/{id}\/sections<\/pre>\n
This retrieves all the properties of the sections – but perhaps you don’t really need them all, maybe you only need the id and the name of the section… in that case, it is better to say:<\/p>\n
GET ~\/notebooks\/{id}\/sections?$select=id,name<\/pre>\n
The same applies to other\u00a0APIs – the fewer properties you select, the better.<\/p>\n
Use $expand instead of making multiple API calls<\/h3>\n
Suppose you want to retrieve all of the user\u2019s notebooks, sections, and section groups in a hierarchical view.<\/p>\n
It can be tempting to do the following:<\/p>\n
    \n
  1. Call GET ~\/notebooks to get the list of notebooks<\/li>\n
  2. For every retrieved notebook, call GET ~\/notebooks\/{notebookId}\/sections to retrieve the list of sections<\/li>\n
  3. For every retrieved notebook, call GET ~\/notebooks\/{notebookId}\/sectionGroups to retrieve the list of section groups<\/li>\n
  4. \u2026 optionally recursively iterate through section groups<\/li>\n<\/ol>\n
    While this will work (with a few extra sequential roundtrips to our service), there is a much better alternative.\u00a0See our blog post about expand<\/a>\u00a0for a more details.<\/p>\n
    GET ~\/api\/v1.0\/me\/notes\/notebooks?$expand=sections,sectionGroups($expand=sections)<\/pre>\n
    This will yield the same results in one network roundtrip with way better performance \u2013 yay!<\/p>\n
    When getting all pages for\u00a0a user, do so for each section separately<\/h3>\n
    While we do expose an endpoint to retrieve all pages, this isn’t the best way to get all the pages the user has access to – when the user has too many sections, this can lead to timeouts\/bad performance. It is better to iterate each section, getting pages for each one separately.<\/p>\n
    So it is significantly better to do several (especially if you don’t need all sections):<\/p>\n
    GET ~\/sections\/{id}\/pages<\/pre>\n
    Than several (this API is paged, so you won’t be able to fetch them all at once):<\/p>\n
    GET ~\/pages<\/pre>\n
    When getting page metadata, override default lastModifiedDate ordering<\/h3>\n
    It is faster for us to get pages when we don’t have to sort them by lastModifiedDate (which is the default ordering) – you can achieve this by sorting by any other property:<\/p>\n
    GET ~\/sections\/{id}\/pages?$select=id,name,creationDate&$orderby=creationDate<\/pre>\n
    Happy coding,\nJorge<\/p>\n","protected":false},"excerpt":{"rendered":"
    Hello world, In StackOverflow and twitter, we often hear questions on how to make queries to the API faster. Here are a few recommendations: Always log the “X-CorrelationId”, “Date” and “Request-Processing-Time” headers on the OneNote API response First – make sure you have the API’s performance-related information logged. All requests to the OneNote API have […]<\/p>\n","protected":false},"author":69223,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[11],"tags":[71],"class_list":["post-1270","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-office-add-ins","tag-onenote"],"acf":[],"blog_post_summary":"
    Hello world, In StackOverflow and twitter, we often hear questions on how to make queries to the API faster. Here are a few recommendations: Always log the “X-CorrelationId”, “Date” and “Request-Processing-Time” headers on the OneNote API response First – make sure you have the API’s performance-related information logged. All requests to the OneNote API have […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1270","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69223"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=1270"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1270\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=1270"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=1270"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=1270"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}