And SharePoint makes three!
The OneNote team is happy to announce support for SharePoint site-hosted notebooks (in Preview). This means you can access all your notebooks on the Microsoft cloud! This includes:
- OneDrive-hosted personal notebooks
- OneDrive for Business-hosted notebooks on Office 365 (also in Preview)
- OneDrive for Business-hosted notebooks on SharePoint
Last month, we described our support for enterprise notebooks on Office 365 (new service root URL, auth model, permissions, app registration, etc.). All that pretty much applies to SharePoint site-hosted notebooks, too. The main difference for accessing OneNote content on SharePoint is the service root URL.
Service root URL
This is the pattern you use to access OneNote content on SharePoint sites:
https://www.onenote.com/api/{version}/myorganization/siteCollections/{id}/sites/{id}/notes/
The myorganization segment in the path represents the tenant that the user is logged into. (Currently, that's the only supported tenant.) Everything that comes after /notes is basically the same across services. For example, this example request gets the 10 most recently modified pages from the notebooks on the site that you have permissions to access:
Get the site collection and site IDs
We added the FromUrl method so you can pass in an absolute site URL and get the site collection and site IDs. You should make this call only when needed, and then store the values for future use in your requests to the OneNote API. The site URL depends on your config, for example https://domain.sharepoint.com/site-a or https://domain.com/sites/site-a.
GET https://www.onenote.com/api/beta/myorganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')
Authorization: Bearer {access-token}
Accept: application/json
Here's an example response:
{
"@odata.context":"https://www.onenote.com/api/beta/$metadata#Microsoft.OneNote.Api.SiteMetadata",
"siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5",
"siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"
}
Parity with consumer APIs
All currently supported HTTP operations have equivalent support for enterprise notebooks, with a few exceptions. For example:
- POST ~/notes/pages is currently not supported. To create a page, you have to include the section ID: ~/me/notes/sections/{id}/pages. Using the ?sectionName parameter to create a page is not supported yet either.
- The $search query option is currently not supported.
You can see our supported HTTP operations here, but note that the docs and interactive calls currently target consumer notebooks on OneDrive only.
There's a couple other things you might run into when working with notebooks on SharePoint:
- You can only create OneNote notebooks, sections, and pages on sites that have a default document library. (Some site templates don't create a default document library.) However, GET requests return OneNote content from all document libraries on the site.
- The OneNote service root URL is immutable, meaning you can't use a SharePoint REST API site path and then tack the /notes endpoint onto it.
And the rest...
Authentication and authorization
The auth model is the same as Office 365. Learn more about Office 365 authentication and authorization.
App registration and permission scopes
You'll specify permissions for your apps when you register an application on Azure AD. The registration process and permission scopes for enterprise notebooks are described in this post. You'll need the Notes.Read.All or Notes.ReadWrite.All scope to access SharePoint site-hosted notebooks. In the future, we'll also add support for finding notebooks that are shared with you.
Keep in touch
As always, we'd love to hear what you think about the OneNote APIs and our enterprise notebook support on UserVoice. You can also contact us on twitter @onenotedev, or ask a question tagged onenote on Stack Overflow.
Edit 11/10/2015: Added guidance to use the Notes.Read.All and Notes.ReadWrite.All scopes to access SharePoint site-hosted notebooks.