{"id":1269,"date":"2016-01-12T21:57:58","date_gmt":"2016-01-13T05:57:58","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=1269"},"modified":"2021-11-15T11:36:51","modified_gmt":"2021-11-15T19:36:51","slug":"onenote-api-throttling-and-how-to-avoid-it","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/onenote-api-throttling-and-how-to-avoid-it\/","title":{"rendered":"OneNote API throttling and how to avoid it"},"content":{"rendered":"

Hi there,<\/p>\n

Sometimes, applications can be written to be too demanding of an API. If one application is using too many resources, it may accidentally cause a denial of service for other applications by making the API slow or unusable. The OneNote API protects itself against accidental denial of service in the form of preventing requests and returning a “429” HTTP response code when we detect too many – this is known as throttling.<\/p>\n

Before I start talking about\u00a0recommendations for production apps –\u00a0if you’re running into throttling (429’s) during development<\/em><\/strong>, you can simply change your user or your app (this does require giving permissions again) and keep coding\/testing against the API.<\/p>\n

Throttling\u00a0is something you definitely want your app to avoid – here’s a couple of best practices to achieve this:<\/p>\n

Best practice 1 – Reduce network roundtrips,<\/strong>\u00a0especially when retrieving metadata:<\/p>\n

Suppose you want to retrieve all of the user’s notebooks, sections, and section groups in a hierarchical view.<\/p>\n

Bad practice –<\/strong>\u00a0It can be tempting to do the following:<\/p>\n

    \n
  1. Call GET ~\/api\/v1.0\/me\/notes\/notebooks to get the list of notebooks<\/li>\n
  2. For every retrieved notebook, call GET ~\/api\/v1.0\/me\/notes\/notebooks\/{notebookId}\/sections to retrieve the list of sections<\/li>\n
  3. For every retrieved notebook, call GET ~\/api\/v1.0\/me\/notes\/notebooks\/{notebookId}\/sectionGroups to retrieve the list of section groups<\/li>\n
  4. … 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

    Best practice –<\/strong>\u00a0One step!<\/p>\n

      \n
    1. Call GET ~\/api\/v1.0\/me\/notes\/notebooks?$expand=sections,sectionGroups($expand=sections)<\/li>\n<\/ol>\n

      This will yield the same results in one network roundtrip with way better performance – yay!<\/p>\n

      Best practice 2<\/strong>\u00a0–\u00a0Don’t retry requests to the API\u00a0indefinitely<\/strong>, especially without inspecting the HTTP status code or OneNote API error information<\/p>\n

      Suppose you are creating some UI that will give you a string which will then be the name for a new notebook. You’ll use the POST ~\/me\/notes\/notebooks API to create a new notebook with that name.<\/p>\n

      Bad practice\u00a0–\u00a0<\/strong>Infinitely retrying without inspecting API errors\n<\/strong>\n<\/code>\/\/ Pseudocode!\nbool apiSucceeded = false;\nwhile(!apiSucceeded){\ntry{\ncreateNotebookApiRequest.Execute();\napiSucceeded = true;\n\/\/\u00a0^_^\n}\ncatch(Exception ex){\n\/\/ The API request failed!\u00a0????\u00a0Retrying.\n}\n}<\/code><\/p>\n

      Tip\u00a0–\u00a0<\/strong>If our API responds with an HTTP Status Code 4xx (like 404, 400, 409), there is something wrong with the request and retrying won’t help!<\/p>\n

      Best practice –<\/strong>\u00a0Inspect and handle errors, starting with the HTTP response code (also, we might want to set a limit on\u00a0retry loops\u00a0????\u00a0).\nAn example error in this category could be an invalid notebook name (which will result in an HTTP status code “400” and the OneNote API error “NotebookNameInvalidChar”. When this happens, you might want to prompt your user for a different name or trim certain characters off the notebook name.<\/p>\n

      You\u00a0can check out\u00a0Nick’s blog post on OneNote API errors<\/a>\u00a0to see details about how we return specific errors. Also, the list of OneNote API errors is kept up to date\u00a0in our docs<\/a>!<\/p>\n

      As we aim to provide a responsive, stable service for all of our users and developers, we will be enabling\u00a0throttling in our API on\u00a001\/29\/2016<\/strong>.\u00a0Here’s how it will work:<\/p>\n