OneNote Dev Blog

A few performance tips for using the OneNote API

Jorge Aguirre Gonzalez — Fri, 21 Jul 2017 20:25:48 GMT

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 those 3 headers - here's an example:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/xml
Expires: -1
Server: Microsoft-IIS/10.0
X-CorrelationId: d0ff1746-6b9d-456f-ae18-3c7bc822d53e
X-UserSessionId: d0ff1746-6b9d-456f-ae18-3c7bc822d53e
X-OfficeFE: deployment29(8).MSOffice.ClassNotebookApiSingleBox_IN_0
X-OfficeVersion: 16.0.8418.3004
X-OfficeCluster: localhost
P3P: 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"
X-Content-Type-Options: nosniff
Request-Processing-Time: 838.9842 ms
OData-Version: 4.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Fri, 28 Jul 2017 16:54:58 GMT
Content-Length: 32552

X-CorrelationId: This uniquely identifies any API request. In case there are any issues with the API, we can use this for debugging. Request-Processing-Time: Latency of the API. Date: The date when the request was made. Having this in your logs will make debugging performance issues easier.

Use $select to select the minimum set of properties you need

When querying for a resource (say for example, sections inside a notebook), you make a request like:

GET ~/notebooks/{id}/sections

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:

GET ~/notebooks/{id}/sections?$select=id,name

The same applies to other APIs - the fewer properties you select, the better.

Use $expand instead of making multiple API calls

Suppose you want to retrieve all of the user’s notebooks, sections, and section groups in a hierarchical view. It can be tempting to do the following:

Call GET ~/notebooks to get the list of notebooks
For every retrieved notebook, call GET ~/notebooks/{notebookId}/sections to retrieve the list of sections
For every retrieved notebook, call GET ~/notebooks/{notebookId}/sectionGroups to retrieve the list of section groups
… optionally recursively iterate through section groups

While this will work (with a few extra sequential roundtrips to our service), there is a much better alternative. See our blog post about expand for a more details.

GET ~/api/v1.0/me/notes/notebooks?$expand=sections,sectionGroups($expand=sections)

This will yield the same results in one network roundtrip with way better performance – yay!

When getting all pages for a user, do so for each section separately

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. So it is significantly better to do several (especially if you don't need all sections):

GET ~/sections/{id}/pages

Than several (this API is paged, so you won't be able to fetch them all at once):

GET ~/pages

When getting page metadata, override default lastModifiedDate ordering

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:

GET ~/sections/{id}/pages?$select=id,name,creationDate&$orderby=creationDate

Happy coding, Jorge

OneNote Ink BETA Apis

Jorge Aguirre Gonzalez — Fri, 07 Jul 2017 20:37:31 GMT

Hello developers, For a while, we've been hearing that you are looking to create integrations that involve ink - however our REST API didn't support interactions with ink... until today. We're releasing APIs in beta that allow you to send/receive ink content in addition to normal content from OneNote - they work for both Microsoft accounts and O365 Organizational accounts. Here's how they work:

Reading ink from OneNote pages

You can read OneNote page content by using our GET ~/pages/{id}/content API. You can now also get ink content by adding ?includeInkML=true as a query param when calling this API. When specified, we will return a multipart response with both OneNote "normal" content as HTML, and OneNote ink content as InkML. InkML is a w3c standard for expressing ink content - we support a subset of it (see below for full description). I've found InkMLJs is a useful library for rendering InkML.

GET https://www.onenote.com/api/beta/me/notes/pages/0-2350a40e7c4e43a1b1d512f6fbf29901!10-26D4802B774E3023!131/content?includeInkML=true HTTP/1.1
Authorization: Bearer ...

Writing ink to OneNote pages

You can write OneNote page content by using our POST ~/pages API. You can now also write ink content by including another part in your multipart request with Content-Type "application/inkml+xml" and content name "presentation-onenote-inkml". Here's an example request

POST https://www.onenote.com/api/beta/me/notes/pages HTTP/1.1
Content-Type: multipart/form-data; boundary=43706cbec49f4b73a2221b6da7c85140
Authorization: Bearer ...
Content-Length: 7802
Expect: 100-continue

--43706cbec49f4b73a2221b6da7c85140
Content-Type: text/html
Content-Disposition: form-data; name=presentation


 
 
 Page with InkML
 
 
 
--43706cbec49f4b73a2221b6da7c85140
Content-Type: application/inkml+xml
Content-Disposition: form-data; name=presentation-onenote-inkml



 
  
   
    
     
     
     
    
    
     
     
     
    
   
  
  
   
   
   
   
   
   
   
   
   
  
 
 
  1423 7569 3456, 1468 7288 7040, 1506 7176 7168, 1599 7006 7168, 1744 6768 7168, 1952 6474 7168, 2228 6128 7168, 2583 5737 7168, 3001 5313 7168, 3483 4854 6784, 4007 4413 6400, 4548 3999 6144, 5059 3657 6016, 5530 3402 5888, 5921 3244 5888, 6213 3196 5632, 6421 3253 5504, 6532 3413 5760, 6545 3700 6016, 6427 4130 6400, 6170 4678 6912, 5797 5314 7936, 5331 6012 9088, 4792 6748 9728, 4225 7506 10496, 3709 8257 11008, 3239 8965 11520, 2890 9600 11648, 2671 10148 11776, 2574 10600 11648, 2605 10958 11520, 2725 11259 11648, 2972 11481 11776, 3347 11603 11904, 3876 11632 12160, 4544 11569 12032, 5317 11410 12032, 6174 11202 11776, 7083 10983 11520, 7974 10779 10752, 8811 10628 10112, 9566 10531 8960, 10191 10497 7936, 10706 10542 7424, 11084 10644 7040, 11333 10804 6912, 11469 11040 6912, 11484 11367 6784, 11385 11817 6656, 11152 12374 6528, 10795 13023 6400, 10376 13722 5888, 9906 14458 5504, 9460 15181 5376, 9096 15845 5376, 8854 16410 3584, 8741 16914 1920, 8757 17335 1024, 8893 17699 256
  12105 14014 2560, 11649 14071 3840, 11047 14166 5120, 10839 14195 4992, 10549 14222 5504, 10237 14227 6144, 9909 14199 7040, 9622 14125 7936, 9375 13991 8704, 9181 13790 9472, 9045 13516 9856, 8977 13152 10368, 8986 12709 10368, 9088 12189 10368, 9250 11614 10240, 9475 11031 10240, 9742 10459 10112, 10020 9923 10112, 10277 9438 9984, 10492 9022 9856, 10655 8667 9856, 10748 8376 9856, 10777 8140 9856, 10751 7959 9856, 10656 7819 9856, 10504 7726 9984, 10285 7668 10112, 10018 7668 10240, 9680 7720 10240, 9293 7824 10240, 8898 7982 10240, 8491 8177 10368, 8115 8387 10112, 7794 8584 9984, 7547 8740 9472, 7387 8839 8960, 7334 8875 7808, 7362 8846 6784, 7504 8715 3456, 7800 8473 256
  9674 7756 5632, 9350 7776 8448, 8993 7925 11904, 8909 7989 12544, 8787 8104 12928, 8647 8263 13440, 8502 8455 13440, 8370 8681 13568, 8250 8925 13440, 8149 9190 13312, 8070 9448 12928, 8017 9690 12672, 7988 9900 12416, 7988 10076 12160, 8022 10210 12032, 8090 10293 11904, 8212 10327 12032, 8382 10298 12288, 8624 10205 12160, 8914 10040 12160, 9253 9807 12032, 9612 9542 11904, 9975 9258 11648, 10302 8977 11520, 10569 8740 11520, 10782 8557 11648, 10931 8434 12160, 11008 8362 12672, 11033 8339 13184, 11015 8371 13696, 10950 8455 13696, 10834 8599 13696, 10692 8789 13952, 10533 9031 14208, 10373 9309 14336, 10214 9613 14464, 10083 9929 14336, 9992 10239 14336, 9952 10526 14208, 9977 10773 14208, 10052 10981 14080, 10194 11146 13952, 10384 11253 13824, 10651 11307 13696, 10974 11304 13056, 11354 11248 12544, 11766 11153 12160, 12176 11040 11776, 12560 10918 11520, 12884 10813 11264, 13133 10744 11136, 13316 10705 11136, 13433 10714 10752, 13492 10755 10368, 13495 10841 9600, 13454 10954 8960, 13390 11103 7296, 13307 11264 5760, 13230 11429 3712, 13158 11580 1792, 13094 11734 1024, 13037 11867 256
  8190 7100 3328, 7857 7096 4992, 7592 7062 6144, 7556 7037 5760, 7531 6978 6784, 7533 6881 7808, 7592 6736 7808, 7701 6539 7936, 7886 6295 7808, 8133 6017 7808, 8452 5707 8192, 8794 5397 8576, 9153 5110 8832, 9468 4877 9088, 9719 4698 9344, 9895 4583 9600, 9995 4524 10112, 10015 4524 10624, 9957 4592 10752, 9816 4732 11008, 9599 4947 11520, 9350 5209 12032, 9099 5490 13056, 8864 5777 14208, 8685 6033 14592, 8581 6252 14976, 8569 6422 14464, 8624 6551 13952, 8767 6636 12672, 8977 6677 11520, 9255 6682 10880, 9572 6659 10368, 9904 6620 10240, 10233 6577 10240, 10544 6539 10496, 10811 6514 10752, 11035 6505 11392, 11217 6528 12032, 11357 6582 12288, 11450 6670 12672, 11502 6801 12544, 11513 6969 12416, 11474 7193 12160, 11382 7455 12032, 11246 7765 11776, 11083 8106 11520, 10898 8459 11264, 10734 8803 11136, 10606 9115 11008, 10540 9368 11008, 10533 9554 10368, 10588 9687 9856, 10708 9764 8064, 10898 9778 6272, 11146 9744 3968, 11454 9658 1664, 11775 9554 896, 12094 9420 128
  8739 9547 1152, 8622 9531 1664, 8642 9497 1280, 8664 9463 128
  11701 13399 4480, 11644 13267 6656, 11766 12951 9216, 11852 12836 9344, 11990 12652 9600, 12212 12408 9856, 12485 12128 9984, 12795 11847 10240, 13117 11585 10368, 13413 11370 10496, 13676 11205 10624, 13890 11098 10752, 14044 11040 11008, 14151 11031 11392, 14209 11071 11392, 14225 11160 11520, 14196 11297 11520, 14128 11476 11520, 14031 11702 11648, 13908 11958 11904, 13762 12245 12544, 13617 12544 13312, 13486 12826 13312, 13386 13073 13440, 13327 13283 13440, 13307 13446 13440, 13330 13562 13312, 13400 13645 13312, 13510 13684 12928, 13648 13686 12672, 13827 13670 12416, 14017 13638 12160, 14200 13598 12160, 14359 13573 12160, 14485 13564 12160, 14578 13582 12160, 14632 13638 12288, 14646 13734 12416, 14615 13874 12416, 14544 14048 12544, 14438 14256 12288, 14311 14486 12160, 14182 14728 12160, 14058 14970 12160, 13958 15179 12032, 13884 15362 12032, 13847 15506 11392, 13845 15617 10752, 13875 15688 9984, 13942 15719 9344, 14044 15712 8320, 14171 15660 7424, 14316 15567 6272, 14465 15441 5120, 14617 15292 2688, 14753 15120 384, 14854 14937 256, 14917 14762 256
 

 
--43706cbec49f4b73a2221b6da7c85140--

Our InkML format follows the following description:

InkML:context can be either "ctxCoordinatesWithPressure" or "ctxCoordinatesOnly". The only difference is that the latter doesn't include the channel "F" for pressure.
X and Y axis in OneNote have their origins at the top left corner of the page and increase as you go right and down respectively.
1 Himetric = 1/1000 cm
Coordinates must be expressed as integers
Specifications on brush properties
1. transparency goes from 0 to 256, where 0 is opaque
2. tip can be "ellipse" or "rectangle"
3. rasterOp determines how the stroke interacts with other strokes (above it, below it, etc). Possible values are: maskPen, copyPen, noOperation
Ink traces should always have a unique id and should always reference a brush and a context.

Please note that this feature is in beta. We are opening it up to allow developers to try it out and use it, but it has the following limitations:

For GET, some types of ink are not returned yet. Specifically some formats created by the OneNote Win32 client. This can be worked around by selecting ink in the OneNote Win32 client, right click, then "treat as drawing". You can also disable this behavior from the OneNote Win32 client by going into File, Options, Advanced "Enable automatic handwriting recognition" and switching that option off.
For POST, there is no "developer friendly" validation of the InkML document provided. If it is invalid, we will throw a 500. I'd recommend starting with the sample above and trying to produce a similar version from your code.
The structure of the API might change in the future, as this is still beta - though I consider this unlikely
As all of our beta APIs, we don't consider them to be production ready yet for the reasons above

As always reach out to us via stackoverflow (tag onenote-api) or twitter (@OneNoteDev) for any questions. I am excited to see what kinds of integrations you will come up with - happy coding!

Get Recent Notebooks API

Manjusha Mangaonkar — Fri, 21 Apr 2017 21:00:13 GMT

Hello, One of the most commonly used scenario in OneNote clients is to open your notebook, File => Open => Open Notebook Or in some OneNote clients, there is a Home => More Notebooks dialog. Or if you login to https://www.onenote.com you will see a list of Recent notebooks like this: For all these above scenarios and many more, we have a new API called GetRecentNotebooks. Here's how you can call it (with your Microsoft or Work account):

GET https://www.onenote.com/api/v1.0/me/notes/notebooks/getrecentnotebooks(includePersonalNotebooks=true)

This will return the following JSON payload:

There is a flag to specify whether you want to include your owned personal notebooks in the API response or not. Here's how you can specify the "includePersonalNotebooks" flag:

GET https://www.onenote.com/api/v1.0/me/notes/notebooks/getrecentnotebooks(includePersonalNotebooks=true) OR GET https://www.onenote.com/api/v1.0/me/notes/notebooks/getrecentnotebooks(includePersonalNotebooks=false)

You can use this API to keep track of all your recently accessed notebooks. Or to quickly access a notebook that you recently visited. Since the API always returns your recent notebooks sorted by most recently used, this is a pretty neat way to get your recent most notebook at the top of the list. Manjusha

OneNote Service Scopes update

sharad sharma — Tue, 24 Jan 2017 20:14:04 GMT

This is Sharad from EDU/OneNote team. This blog post is aimed at providing updates with respect to OneNote scopes and related changes in Azure Active Directory. We are enabling two new permissions (for O365) which will have wider access scope for OneNote resource.

Scope (enterprise)	Old Permission text in Azure portal	Revised Permission text in Azure portal	Purpose
Notes.Read.All	View OneNote notebooks in your organization	View user’s notes and notes shared with user	Allows the user to view OneNote notes that the signed-in user has access to in the organization. The user cannot access password-protected sections.
Notes.ReadWrite.All	View and modify OneNote notebooks in your organization	View and modify user’s notes and notes shared with user	Allows the user to view and modify OneNote notes that the signed-in user has access to in the organization.

These scopes are available as delegate permission (not requiring admin consent). These scopes allow the caller to access anything in the organization (outside calling user’s OneDrive) where caller has access to notes shared under sitecollections/{id}/sites/{id} or groups/{id} or users/{id}. To maintain backward compatibility, these routes will continue to support Notes.Read and Notes.ReadWrite scopes. However, moving forward, one should expect only newer (i.e. Notes.Read.All and Notes.ReadWrite.All) scopes being supported for these routes. It is recommended to use these newer scopes. We have also revised the name and description of below OneNote scopes (for O365)

Scope (enterprise)	Old Permission text in Azure portal	Revised Permission text in Azure portal	Permission
Notes.Create	Create pages in OneNote notebooks	Create user’s notes	Allows the user to create OneNote notes for the signed-in user.
Notes.ReadWrite.CreatedByApp	Application-only OneNote notebook access	View and modify notes created using given application	Allows the user to view and modify OneNote notes created by this app. The user cannot view or modify notes created by other apps or under password-protected sections.
Notes.Read	View OneNote notebooks	View user’s notes	Allows the user to view OneNote notes for the signed-in user. The user cannot read notes under password-protected section.
Notes.ReadWrite	View and modify OneNote notebooks	View, modify user’s notes	Allows the user to view and modify OneNote notes for the signed-in user.

More details on scopes and authentication are available here.

OneNote API calls fail with a large number of items in a SharePoint document library

Paresh Moradiya — Sun, 11 Sep 2016 16:40:24 GMT

Hello world! Paresh Moradiya and Sri Srinivasan, members of the OneNote API team here. We've heard from some of you saying that you're running into issues when accessing SharePoint-hosted notebooks in very large document libraries. We have come up with some instructions on how you can eliminate these OneNote API failures.

The problem

Applications call the OneNote REST API to create or access OneNote content in Office 365. Sometimes the OneNote API calls can fail when they are executed against SharePoint document libraries that contain a large number of items (items can be folders or files, some of which could be OneNote entities such as notebooks, sections or section groups). When working with SharePoint document libraries that contain a large number of items, the OneNote API service is subject to throttling measures implemented by SharePoint for the purposes of regulating resource usage. Under these circumstances, the user of the application may see an application-specific error. The application calling the OneNote API will itself receive one of the errors below: { "error": { "code": "10008", "message": "One or more of the document libraries on the user or group's OneDrive contains more than 5,000 OneNote items (notebooks, sections, section groups) and cannot be queried using the API. Please make sure that none of the user or group's document libraries contains more than 5,000 OneNote items. Please follow the link below for instructions on how to remedy this situation.", "@api.url": "https://aka.ms/onenote-errors#C10008" } { "error": { "code": "10013", "message": "One or more of the document libraries on the user or group's OneDrive contains more than 20,000 items and cannot be indexed for querying using the API. Please follow the link below for instructions on how to remedy this situation.", "@api.url": "https://aka.ms/onenote-errors#C10013" }

The solution

To mitigate the OneNote API failures described above, you must first assess the current state of the SharePoint document libraries on the SharePoint site and then take a few remedial steps based on the current state.

Assess the current state

Download the OneNote API Diagnostics tool available here and follow the steps below.

Enter the following parameters into the tool

Parameter	Description
SharePoint URL	The SharePoint site's URL. For example, a user's personal site might use the format `https://<>-my.SharePoint.com/personal/<>` (contact your administrator for the format of your personal site's URL) You can also enter the URL for a non-personal SharePoint site
User	Your Office 365 user name (email address)
Password	Your office 365 password

Click the "Get Info" button. This will fetch the diagnostic information from the specified SharePoint site. The operation may take a few seconds to process.

NOTE: The tool processes only the default document library on the SharePoint site by default (for a user's personal site, this is the user's OneDrive for Business). If the API issues above are not resolved by just targeting the default document library, you can choose the tool's option to target all document libraries on the SharePoint site.

Take appropriate remedial steps

Based on the output of the diagnostics tool, you can take the remedial steps suggested below. These steps are applicable at a document library level. If you chose to target all document libraries on the SharePoint site, you will need to execute the remedial steps below on all the document libraries. Case 1: Items Count is greater than 20,000 If Items Count is greater than 20,000 and File Type = false or HTML File Type = false, then you need to bring the item count in the document library to under 20,000. You can do this by moving items out of the document library to a different storage location (such as another user or group's OneDrive). You can also delete the items that are not required anymore. After you have reduced the item count to under 20,000, rerun the tool to make sure the items count is less than 20,000. Click the "Build Index" button so the required indexes are built for the OneNote API to work properly. Case 2: Sections Count is greater than 5,000 If Sections Count is greater than 5,000, then you need to bring the section count in the document library to under 5,000. You can do this by moving some of your notebooks out of the document library to a different storage location (such as another user or group's OneDrive). You can also delete the notebooks that are not required anymore. After you have reduced the section count to under 5,000, rerun the tool to make sure the sections count is less than 5,000. Ideally you should keep this number below 5,000 so that you can have enough room to create new sections. If the sections count in the document library crosses 5,000 again, you will start seeing the OneNote API failures and you will need to come back here and take the same remedial steps. Case 3: Folders Count is greater 5,000 If Folders Count is greater than 5,000, then you need to bring the folder count in the document library to under 5,000. You can do this by reorganizing the content in the document library and eliminating folders. You can also delete the folders that are not required anymore. After you have reduced the folder count to under 5,000, rerun the tool to make sure the folder count is less than 5,000. Ideally you should keep this number below 5,000 so that you can have enough room to create new folders. If the folder count in the document library crosses 5,000 again, you will start seeing the OneNote API failures and you will need to come back here and take the same remedial steps. Case 4: Notebooks Count is greater than 5,000 If Notebooks Count is greater than 5,000, then you need to bring the notebook count in the document library to under 5,000. You can do this by moving some of your notebooks out of the document library to a different storage location (such as another user or group's OneDrive). You can also delete the notebooks that are not required anymore. After you have reduced the notebook count to under 5,000, rerun the tool to make sure the notebook count is less than 5,000. Ideally you should keep this number below 5,000 so that you can have enough room to create new notebooks. If the notebook count in the document library crosses 5,000 again, you will start seeing the OneNote API failures and you will need to come back here and take the same remedial steps.

The Web Clipper Goes Open-Source

Matthew Chiam — Wed, 31 Aug 2016 21:52:30 GMT

Hello! This week, we are excited to announce the open-sourcing of the OneNote Web Clipper under the MIT License. Install: https://www.onenote.com/clipper GitHub: https://github.com/OneNoteDev/WebClipper Wiki: https://github.com/OneNoteDev/WebClipper/wiki For those who are unfamiliar with the extension, the OneNote Web Clipper is an extension for all major browsers that allows you to clip content from the web directly into OneNote. A lot has changed since we first started, and our team would like to share the behind-the-scenes happenings on the engineering side – from the Web Clipper’s first inception to the tool that it is today.

A Trip Down Memory Lane It has been more than two years since we first released the OneNote Web Clipper in early 2014. When it first released, the extension had only one function, that is, to take a full-page screenshot of the user's current web page. While this was a decent first start, we quickly learned that users wanted more tools to extract meaningful content from web pages. Less than a year later, we began work on what we dubbed Web Clipper v2. With this version, we added the ability for users to select and clip a partial screenshot of the current web page - known as 'Region' mode. We also added the ability for the Web Clipper to determine if a page can be best described as an article, product, or recipe. The extension would then extract out the content of the page minus all the elements we thought the user wouldn't want, such as adverts, and format the content in a meaningful way. For example, if we detected that the page was a recipe, we would extract the ingredients and steps and format it nicely for the user to add to their notebook. Finally, we added the simple but highly-requested ability for the user to save the clip to any section in their notebooks.

The Ugly Bits While our team was excited to release Web Clipper v2, we quickly realized that there were severe flaws in our design. First of all, v1 and v2 were written from scratch without leveraging libraries or frameworks that would have made our development lives easier. Shortly after the release of v2, our next task was to simply "allow the user to change the title of the page before submitting it to OneNote". What was originally thought to be a simple change became an exercise in futility as we recognized that even the smallest changes would require re-writing large portions of the Web Clipper due to all the codebase's interlocking dependencies. The primary reason for this was the fact that we had tried to reinvent the wheel for just about everything - UI, animations, the works. In particular, most of the UI was declared in a single, monolithic .cshtml file that brought about huge extensibility and scalability issues. Rather than looking to the outside world to find solutions to our problems, we (ironically) created more problems by trying to reinvent existing solutions. Another symptom of our software's design choices was the lack of testability. The old codebase was by no means modular in nature, and in order to execute a section of the code, you essentially had to invoke the extension in its entirety. Unit-testing was near-impossible, and we had to rely on archaic methods of testing involving lots of checkboxes and time spent running the Web Clipper through different use-case scenarios. We investigated using end-to-end test frameworks to automate these scenarios, but we realized that with every new feature that we wanted to add, we'd be increasing the number of test scenarios exponentially. Finally, Web Clipper v2 suffered from performance issues as the result of a design decision we made early on in our development process. Originally, Web Clipper v1 was a bookmarklet. Bookmarklets did not support auto-updates of any sort like extensions do, so we decided that bookmarklets should download the latest Web Clipper scripts from our servers on each invocation. As we moved on with Web Clipper v2, we wanted to build the Web Clipper as an extension across all the major browsers. However, rather than leveraging the extensions' ability to self-update, we wrote the extensions as wrappers for the bookmarklet. This was a major source of the performance issues (in the form of a noticeable delay on every invocation of the Web Clipper), and also exposed us to other problems because of more prevalent Content Security Policies and content blockers. As a result, many of our users were frustrated. We knew we had to re-write the Web Clipper, so later that year, we said goodbye to the old way of doing things, and started anew.

Building a Better Web Clipper If we could choose three words to describe Web Clipper v3's new architectural goals, they would be "modifiability", "performance", and "testability". We knew that without all three, it would be difficult to iterate quickly on new features and delight users. Over the course of several months, we broke apart the old code base and cobbled it back together in a different form. We had to rethink about how we were to rewrite the Web Clipper, and we figured that it boiled down to a few key principles:

Plan for the quality attributes you care about right from the beginning. Don't be afraid to commit the time necessary to come up with a software design that meets your goals. The days you put into this will pay dividends for the years to come.
Leverage open-source projects where appropriate to solve problems you run into. Especially so in the world of web, if you want to get something done, somebody might have already come up with a tried and tested solution. Do not be afraid to use it.
Use the right tool for the job. You've probably heard this one before, but it's always worth reiterating.
Test aggressively. Before writing anything, ask yourself if your design is testable. Don't limit yourself to just writing unit tests for pure functions. Plan tests for things like UI component rendering logic and HTTP responses too!

First of all, we took extra care to ensure that everything, especially our UI, was modular. We investigated a selection of different UI frameworks, and we made the decision to use a UI framework called Mithril. Using the framework, we enforced a strict tree-like structure for our rendering logic, allowing us to drill down and test individual components in isolation, as well as write tests for multiple components working together at higher levels of the tree. This also meant that we were able to easily replace UI components as we continued iterating on our interface designs. Additionally, we took full advantage of auto-updating extensions and modified our code to treat the bookmarklet and extensions differently, while sharing our code across the different platforms as much as possible. This meant that extensions would now update by themselves, rather than them having to query our servers for the latest scripts on every invocation. In March of 2016, a user posted a review on the Chrome Web Store complaining that our extension was slow to start up. Coincidentally, a day later, we shipped Web Clipper v3. The user returned to the Chrome Web Store shortly after to update his rating, praising the team for the performance improvement, and funnily enough, our 'urgency' in addressing his issue. While the user thought we fixed his concerns in just a day, it actually took us months of work and planning, and his comment made it loud and clear that it was all worth it. Finally, we looked to keep technical debt at reasonable levels. In addition to traditional unit testing and the component-level testing mentioned above, we strived to learn new ways to test our code. We made use of a library called sinon to ensure that our code could react to the different ways our remote endpoints could respond. Sinon also enabled us to shave off a lot of boilerplate code in our tests by providing stubbing/mocking functionalities. Using mocking and dependency injection, we were able to test how different components integrated together. Now that we had a solid test suite up and running, we knew (with high confidence) if we broke something in one of our changes as soon as we ran the build command. Tests even included the 'smaller cases' such as ensuring that the tab index ordering of interactable elements in our UI was exactly the way we wanted it. While we did not release any new features with Web Clipper v3, we quickly started to work through the backlog of features that we created for ourselves in the past. We began by starting where we left off - "allow the user to change the title of the page before submitting it to OneNote". A few days later, a couple of our team's engineers excitedly demonstrated not only an editable title, but highlightable content and modifiable font-family and font-sizes. Another engineer had successfully ported the page preview to all the clipping modes, allowing the user to see exactly what is being saved to OneNote. He had also added the ability for the user to save multiple partial-screenshots of the page all in one go. We moved quickly, and we were excited.

The Journey Ahead It's been several months since we shipped Web Clipper v3, and since then we overhauled the interface, added the preview-viewer across all modes, the ability to clip the page as a 'bookmark', selections (through the browser's context menu), font tweaking, highlighting, multiple region-screenshot selections, changelog notifications, and of course, an editable title. Our users have finer control over what they choose to clip to OneNote, but that doesn't mean the work is over. Recognizing the benefits of 'free' software, we have decided to open-source the Web Clipper, knowing that we have much to learn from the developer community around us. From now on, all our work on the extension will be open for everyone to see and participate in. You will be able to use the Issues tool to submit feedback, questions, suggestions, and bug reports. If you want to get your hands dirty and submit code of your own, feel free to submit a Pull Request. The team will be more than happy to have a look! Over the past couple of years, we have learned a lot, and we continue to do so today. Our code still isn't perfect, but we're constantly reminding ourselves to be open to new technologies and processes. We are extremely excited to begin this new journey in the development of the Web Clipper, and we hope you can join us in building an extension that note-takers everywhere can be excited about. If you have any questions, feedback, or if you just want to say hi, feel free to send us an email at onewebclipper@microsoft.com

Page Preview API

Jorge Aguirre Gonzalez — Mon, 23 May 2016 16:49:35 GMT

Hi OneNote Developers, A common scenario when using the OneNote API is to display a list of pages for the user to take action (for example, get some of their content into your app). Displaying only the page title communicates a limited amount of information about the page to the user. Certain OneNote clients display a more friendly version of a page, including a text preview, an optional image on the page, in addition to the page title and page location. I want to take a moment to talk about a new handy API you can use to solve this problem in your app - page preview. Here's how you can call it: Given a page id, like "0-a68ef66f18110ed12e13342cb6a874b5!1-B669F6A8ED5A07E6!1701" (You can retrieve this with our GET ~/pages API), you can call:

GET https://www.onenote.com/api/v1.0/pages/0-a68ef66f18110ed12e13342cb6a874b5!1-B669F6A8ED5A07E6!1701/preview

This will return the following JSON payload:

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.PagePreview",
  "previewText":"I was almost fired from a job driving the hearse in funeral processions, but then the funeral home realized how much business I was creating for them.",
  "links":{
    "previewImageUrl":{
      "href":"https://www.onenote.com/api/v1.0/resources/0-3154d05d704942daa963a58f28c5880a!1-B669F6A8ED5A07E6!1701/content?publicAuth=true&mimeType=image/png"
    }
  }
}

The previewText property contains a small text snippet from the page (we'll grab text content until completing 300 characters, while maintaining full phrases) that will help the user identify what is in this page. If the page has an image, you will also get a publicly available (you can put this in an tag in a HTML) link to an image in the same way public PCR does it: See Linda's blog post. Using page preview, you can take a page like this: And build a preview that looks like this: As an example, you can combine this API with the OneNote search pages API and build a OneNote pages picker based search terms which displays page previews, similar to the search experience in the OneNote client. Jorge

Office Add-ins on OneNote Online (in Preview)

DianeD [MSFT] — Fri, 01 Apr 2016 09:00:10 GMT

Hello OneNote developers! The OneNote Add-ins team is happy to announce OneNote Online support for the Office Add-in model (in Preview)! Soon you'll be able to develop add-ins for OneNote and make them available world-wide from the Office Store, or upload them to a Corporate Catalog for enterprise access. What's an Office Add-in? An Office Add-is a web application that loads inside an Office application. An add-in can be as simple as a manifest file and a webpage. The manifest tells the Office application about your add-in, like the URL of your web app, what type of add-in it is, and which Office products are supported. The web app is hosted on a web server, so you can easily update it from there.

OneNote supports all three types of add-in:.

Task pane add-ins that open on the side of a OneNote page
Content add-ins that run in the main frame of a OneNote page
Add-in commands that extend the OneNote ribbon and context menu

Watch Vijay's video from Build 2016 to learn more about add-ins and to see a cool demo of the Skim.It Office Add-in running in OneNote Online. Add-ins can be written to support multiple Office applications including Word, Excel, and PowerPoint. Those of you familiar with our REST APIs will find the same top-level hierarchy of notebooks, sections, and pages. However, the new OneNote JavaScript API exposes a more granular object model for working with page content. When developing OneNote add-ins, you'll use the JavaScript API with an asynchronous batch pattern. You can learn more about this in the OneNote add-ins overview or by checking out our Rubric Grader sample. Right now, this is a limited private preview. If you want to start developing OneNote add-ins, you'll need to contact us to get set up with a notebook that you can use for development. In May, we'll make the development environment available to all developers. In Summer 2016, we'll GA and enable support for OneNote add-ins in the Office Store. So start thinking about the great OneNote add-ins you'll create! Contact us @onenotedev with hashtag #requestaddin for more information. Let us know what you think of the OneNote JavaScript APIs! You can post or upvote suggestions on UserVoice and ask questions on Stack Overflow tagged onenote-api. And if you missed Build, check out What's new at Build 2016 for Office Developers.

One time Authentication for Public Resource

LindaLiOneNote — Tue, 22 Mar 2016 23:59:39 GMT

Hi there, The current authentication mechanism is heavy for public image resources. When you retrieve a page content with authenticated token, the image URLs that are referenced still need to have OAuth token added whenever you request them. We heard people from UserVoice Forums want OneNote APIs support preAuthenticated image URLs from a OneNote page that a browser can GET. This new API feature is available now! Once the user has sent an authenticated Page Content Resource request with parameter "preAuthenticated" set to true, it allows browser to fetch the image resource without authentications for a limited time. Its response will contain the public resource URL in a format that shows the resource is a public resource and its content type accordingly. This public resource URL will be available for 1 hour without the need for additional authentication! How can you trigger this feature? Follow these steps: 1. Get the ID of the page with image resources. 2. Send GET page content request with preAuthenticated parameter, for example: GET https://www.onenote.com/api/v1.0/me/notes/pages/{pageId}/content?preAuthenticated=true 3. A response with 200 means it is a successful return. And you can find a resource URL link looks like this: https://www.onenote.com/api/v1.0/me/notes/resources/{resourceId}/content?publicAuth=true&mimeType=image/jpeg 4. The response contains headers with expire UTC datetime and content type of the resource: X-ResourceExpires: 3/21/2016 11:08:27 PM Content-Type: image/gif 5. Now this resource URL is available for 1 hour without the need for additional authentication. Supported Scenarios: • Windows Live Account • Office365 Account with Me/Users/Group/Site scenarios Remarks: The UTC datetime info in header "X-ResourceExpire" shows the exact datetime that the URL is going to expire. Please note that the datetime is set in the header when you request the resource. The actual expire time could be changed if you send the Page Content Resource request with "preAuthenticated=true" again, which will refresh the expiration time with another one hour extension. So you could get different datetime for different resource requests, if you have multiple Page Content Resource calls on the same page in between. The actual expiration time will be the latest one. Examples: • Page Content Resource request: GET https://www.onenote.com/api/v1.0/me/notes/pages/{pageId}/content?preAuthenticated=true • Page Content Resource response: img alt="Rainier.gif" width="279" height="236" src="https://www.onenote.com/api/v1.0/me/notes/resources/{resourceId}/content?publicAuth=true&mimeType=image/gif" data-src-type="image/gif" data-fullres-src="https://www.onenote.com/api/v1.0/me/notes/resources/{resourceId}/content?publicAuth=true&mimeType=image/gif" data-fullres-src-type="image/gif" • Preauthenticated Resource Retrieval request: GET https://www.onenote.com/api/v1.0/me/notes/resources/{resourceId}/content?publicAuth=true&mimeType=image/jpeg • Preauthenticated Resource Retrieval response: X-ResourceExpires: 3/21/2016 11:08:27 PM Content-Type: image/gif References: • Get page content request: https://dev.onenote.com/docs#/reference/get-pages/v10menotespagesidcontentincludeids • Construct the request URI for Me/Users/Group/Site scenario: https://msdn.microsoft.com/office/office365/howto/onenote-get-content#request-uri • Add images and files to OneNote pages: https://msdn.microsoft.com/en-us/office/office365/howto/onenote-images-files Let us know what you think on UserVoice, contact us on twitter @onenotedev, or ask questions tagged onenote on Stack Overflow Have fun, Linda

Change page level

yanirs@gmail.com — Thu, 04 Feb 2016 01:00:00 GMT

Hi there,
In this Beta API update we are allowing developers to change the indentation level for a page (aka page level) programmatically.
For those of you who are unfamiliar with this feature, the following image shows how pages can be indented in three levels:

Here is a quick recipe for how to do this, followed by an example:

Get the ID of the page for which you want to change the indentation level.
Make sure to append the following headers to the request:

A valid Authorization header.
Content-Type set to application/json.

Use the PATCH verb.
The URL for the API is: https://www.onenote.com/api/beta/me/notes/pages/{id}
In the body of the request append the following JSON object:
{"level":"{page level}"}
Replace {page level} with 0, 1 or 2 where 0 means no indentation at all and 2 is the maximum indentation level.
Any response other than a 204 (HTTP no content) means that something went wrong.

Here's an example of what such a request might look like if we wanted to change the indentation level of a specific page to 1:

PATCH https://www.onenote.com/api/beta/me/notes/pages/1-567446387463478
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1...

{"level": "1"}

Gotchas:

The indentation level for the first page in a section cannot be changed, it only works starting at the second page and onwards (if attempted, the request will fail with an HTTP status of 400).
If the page above an indented page is moved to another location or deleted, the indented page will lose its indentation.
The only valid values for the level property are 0, 1, 2.
This API is still in Beta so please don't forget the /beta in the URL.
Please refer to the PATCH content API documentation for additional information about PATCH APIs.

You can use the following APIs to get the value of the current page level:

GET https://www.onenote.com/api/v1.0/me/notes/pages/{id}?pagelevel=true

GET https://www.onenote.com/api/v1.0/me/notes/sections/{id}/pages?pagelevel=true

Please note that you will have to append the pagelevel=true parameter to the request URL.

Let us know what you think on UserVoice, contact us on twitter @onenotedev, or ask questions tagged onenote on Stack Overflow.

Enjoy,
Yanir