New Beta Endpoint & Create Page in Any Location!

Article
06/12/2014

(Updated 7/9/14: These APIs are now in production. The announcement can be found here )

Hello world,

I'm Jorge, an engineer on the OneNote API team and I'm excited to announce that we have a few new features coming your way! Around two months ago we gave you a preview of one of our most wanted features according to our feedback site - "Create a Page in a Specific Section". These are the features that you would use to implement a location picker to allow your user to choose which notebook/section to create a page in. Today, you can try this feature out in our brand new Beta Endpoint.

What Is The Beta Endpoint?

When executing any type of operation against our API, you specify a version:

 POST https://www.onenote.com/api/v1.0/pages

By specifying a beta version, you'll have access to our freshest, newest set of features we offer:

 POST https://www.onenote.com/api/beta/pages

We'll be using the beta endpoint to light up new features earlier than our official, versioned endpoints. When features are announced in the beta endpoint, we plan to keep them there for about a month to gather your feedback and make changes before we officially release them. Our main goal is to give you a sense of what's coming and a chance to give us early feedback, in case you think we could be doing something better :) We'd also like feedback on whether a month is about the right timeframe. One thing to note - we do expect our APIs to change a little when we transition from beta to release, as we're taking feedback, so don't ship a product based on the beta endpoint or we might break you!

You can try all of our APIs in the Beta Endpoint in a new APIGee Console that we have setup for the Beta Endpoint: https://apigee.com/onenote_beta/embed/console/onenote_beta

As a reminder, please send feedback our way either by leaving comments on this blog post, on Twitter @OneNoteDev, or on UserVoice.

How do I Create a Page in a Specific Section?

Creating a page in a specific section is very similar to our existing way to create a page, except you just need to issue the request to a new endpoint:

 POST https://www.onenote.com/api/beta/sections/ {id} /pages

to create a page in a section with this {id} . Our API will take the page content you sent us in the request and create your page in the section you specified. We'll return "201 - Created" and links to the page in the JSON response.

Tip: If you just want to create a page in a top-level section on the user's default notebook, you may want to use our sectionName query parameter instead.

But… How Do I Get the Section ID?

We are also adding functionality in the beta endpoint to enable you to get the complete list of Notebooks, Sections and Section Groups. This allows you to find specific sections within specific notebooks for your users. As Steven mentioned in this preview, here is a summary of the methods you can use to get a list of the user's OneNote elements:

Endpoint	Description
GET ~/Notebooks	Returns details for ALL NOTEBOOKS that the user has access to
GET ~/Notebooks/{id}	Returns details for a SPECIFIC NOTEBOOK
GET ~/Notebooks/{id}/Sections	Returns details for all top-level SECTIONS for a given notebook
GET ~/Notebooks/{id}/SectionGroups	Returns details for all top-level SECTION GROUPS for a given notebook
GET ~/SectionGroups	Returns details for all SECTION GROUPS in ALL NOTEBOOKS that the user has access to
GET ~/SectionGroups/{id}	Returns details for a SPECIFIC SECTION GROUP
GET ~/SectionGroups/{id}/Sections	Returns details for all SECTIONS within a given SECTION GROUP
GET ~/SectionGroups/{id}/SectionGroups	Returns details for all SECTION GROUPS within a given SECTION GROUP
GET ~/Sections	Returns details for all SECTIONS in ALL NOTEBOOKS that the user has access to
GET ~/Sections/{id}	Returns details for a SPECIFIC SECTION

You could issue this request to get all of the user's Notebooks:

GET https://www.onenote.com/api/**beta**/notebooks

 {
 "@odata.context": "https://onenote.com/api/beta/$metadata#notebooks",
 "value": [
 {
 "isDefault": true,
 "userRole": "Owner",
 "isShared": false,
 "links": {
 "sectionsUrl": {
 "href": "https://onenote.com/api/beta/notebooks/0-65F1D98D408863D9!282/sections"
 },
 "sectionGroupsUrl": {
 "href": "https://onenote.com/api/beta/notebooks/0-65F1D98D408863D9!282/sectionGroups"
 },
 "self": {
 "href": "https://onenote.com/api/beta/notebooks/0-65F1D98D408863D9!282"
 },
 "oneNoteWebUrl": {
 "href": "https://onedrive.live.com/redir.aspx?cid=65f1d98d408863d9&page=self&resid=65F1D98D408863D9!282"
 }
 },
 "id": "0-65F1D98D408863D9!282",
 "name": "Tester McTesterson's Notebook",
 "createdBy": "Tester McTesterson",
 "lastModifiedBy": "Tester McTesterson",
 "createdTime": "2014-05-28T23:33:20.9Z",
 "lastModifiedTime": "2014-06-07T01:07:09.677Z"
 },
 {
 "isDefault": false,
 "userRole": "Owner",
 "isShared": false,
 "links": {
 "sectionsUrl": {
 "href": "https://onenote.com/api/beta/notebooks/0-65F1D98D408863D9!288/sections"
 },
 "sectionGroupsUrl": {
 "href": "https://onenote.com/api/beta/notebooks/0-65F1D98D408863D9!288/sectionGroups"
 },
 "self": {
 "href": "https://onenote.com/api/beta/notebooks/0-65F1D98D408863D9!288"
 },
 "oneNoteWebUrl": {
 "href": "https://onedrive.live.com/redir.aspx?cid=65f1d98d408863d9&page=self&resid=65F1D98D408863D9!288"
 }
 },
 "id": "0-65F1D98D408863D9!288"  , 
 "name": "My favorite trips",
 "createdBy": "Tester McTesterson",
 "lastModifiedBy": "Tester McTesterson",
 "createdTime": "2014-05-28T23:58:19.067Z",
 "lastModifiedTime": "2014-05-29T00:04:12.19Z"
 }
 ...otherNotebooks...
 ]
}

We've conveniently placed the sectionsUrl in the links object, so you can easily issue a subsequent call to get all sections inside any notebook. Let's say, the user has chosen to create a page in the "My favorite trips" notebook.

 GET https://www.onenote.com/api/beta/notebooks/0-65F1D98D408863D9!288/sections
{
 "@odata.context": "https://onenote.com/api/beta/$metadata#sections",
 "value": [
 {
 "isDefault": false,
 "links": {
 "pagesUrl": {
 "href": "https://onenote.com/api/beta/sections/0-65F1D98D408863D9!284/pages"
 },
 "self": {
 "href": "https://onenote.com/api/beta/sections/0-65F1D98D408863D9!284"
 },
 "oneNoteWebUrl": {
 "href": "https://onedrive.live.com/redir.aspx?cid=65f1d98d408863d9&page=view&resid=65F1D98D408863D9!284&parId=65F1D98D408863D9!282"
 }
 },
 "id": "0-65F1D98D408863D9!284",
 "name": "Quick Notes",
 "createdBy": "Tester McTesterson",
 "lastModifiedBy": "Tester McTesterson",
 "createdTime": "2014-05-28T23:33:23.393Z",
 "lastModifiedTime": "2014-06-02T17:40:29.12Z"
 },
 {
 "isDefault": false,
 "links": {
 "pagesUrl": {
 "href": "https://onenote.com/api/beta/sections/0-65F1D98D408863D9!287/pages"
 },
 "self": {
 "href": "https://onenote.com/api/beta/sections/0-65F1D98D408863D9!287"
 },
 "oneNoteWebUrl": {
 "href": "https://onedrive.live.com/redir.aspx?cid=65f1d98d408863d9&page=view&resid=65F1D98D408863D9!287&parId=65F1D98D408863D9!308"
 }
 },
 "id": "0-65F1D98D408863D9!287",
 "name": "Trip to Hawaii",
 "createdBy": "Tester McTesterson",
 "lastModifiedBy": "Tester McTesterson",
 "createdTime": "2014-05-28T23:48:40.357Z",
 "lastModifiedTime": "2014-05-29T22:00:12.803Z"
 },
 ...otherSections...
 ]
}

The response contains the section ids you can use to create a page in them, so you could do the following:

 POST https://www.onenote.com/api/beta/sections/0-65F1D98D408863D9!287/pages

to create a page in "Trip to Hawaii".

The structure of the JSON response might still change a bit - we're still discussing some of the finer points of this return packet, and we expect a bunch of feedback on it, so you should definitely expect it to change a little before we go to release. We'll post a heads up here on the blog and on twitter before breaking changes go live on beta.

You can give this a try in our ApiGee beta console ;)

We are excited to see how you're going to use these new features in your apps and looking forward to hearing from you in our blog's comments section as well as on our twitter account @OneNoteDev!

See you soon,

Jorge

Comments

Anonymous
June 13, 2014
Woo Hoo ! About 10 minutes after reading that I had my powerShell scripts posting to my real notebook instead of stupid one live created for me and made my default. 3 lines of PS : (1) get notebooks & choose one (2) get sections from that notebook and choose one. (3) Change the default post location to use that section then I can do PS-Command | out-oneNoteLive -Title "My Stuff" I'll have to update my piece @ www.powershellmagazine.com/.../using-the-windows-live-apis-from-powershell By the way if you want use the PowerShell code for examples you only have to ask
Anonymous
June 16, 2014
Wow !!! Sounds good. Thanx for the update !!!
Anonymous
March 28, 2016
Is there any option to set the order of the pages created in a section ?
- Anonymous
  April 05, 2016
  Hi Vivek. Sorry, we don't currently support that. Can you please submit a request on UserVoice, or upvote this related suggestion? https://onenote.uservoice.com/forums/245490-onenote-developer-apis/suggestions/13174416-ability-to-reorder-page. Thanks!

Share via

New Beta Endpoint & Create Page in Any Location!

Comments

Additional resources