Zapier’s OneNote Integration Journey

  • Article

We are thrilled to have our first guest post on our blog! The following is post from Bryan Helmig of Zapier, who is launching their new OneNote app on Zapier today.

It was right before lunch when we learned that OneNote was launching their API. Naturally, we were very excited about the prospect of quickly bringing OneNote to our user base, though we had one obvious problem: we had never seen their API before!

Here's how we acted on our excitement that day and within three hours integrated OneNote to Zapier:

The first stop was the OneNote Dev Center, where I began by looking for keywords that would clue me in on the style of API, luckily I spotted some references to REST and OAuth. While we work with hundreds of different flavored APIs at Zapier, common patterns like REST and OAuth make our lives very easy.

Within 10 minutes, I had a pretty good understanding of what the OneNote API could do, how we'd authenticate it and how we'd utilize it. The Dev Center contains some particularly good pages, all enumerated in the wonderful how to section.

Next, I created a OneNote app inside the Zapier Developer Platform and started configuring it according to the OneNote API documentation. Let's cover the basics:

Authenticating

First, you'll need a client ID and secret. You'll find those assets at account.live.com/developers/applications, which is where you'll also be able to manage your applications.

Before you continue, double-check your redirect URL, making sure it matches your domain (but just the root domain, not the full URL). It took a little shuffling around to find the right Windows Live ID; we were getting Redirect URLs in use errors.

Next up are the values you'll want to pay attention to:

  • Authorization URL - `https://login.live.com/oauth20_authorize.srf`
  • Token URL - `https://login.live.com/oauth20_token.srf)`
  • Scope - `office.onenote_create wl.signin wl.offline_access`

Don't forget the `wl.signin` and `wl.offline_access` scopes, or else your app will only work for a brief period of time. At the time of writing this, there isn't a `office.onenote_read` scope, but in the future you might want your app to have that ability, as well.

Then go through the standard OAuth flow—you can read more about it from Microsoft here.

Finally, place the access token in the header as a bearer token like `Authorization: Bearer tokenString`.

It took us about 30-40 minutes to get all the authentication information straightened out, and really that was just due to having a few intermingled live accounts with some URL conflicts.

Creating Your First Note

Creating notes in OneNote is very, very simple! For the most basic of notes all you need is:

For example:

 POST https://www.onenote.com/api/v1.0/pages
    
Content-Type: text/html
     
Authorization: Bearer tokenString
     
<!DOCTYPE html> 
<html> 
 <head>
 <title>Title of a OneNote Note</title>
 <meta name="created" value="2013-06-11T12:45:00.000-8:00"/> 
 </head>
    
 <body> 
 <p>This is just standard HTML, you know this!</p> 
 </body> 
</html>

But that isn't all, you can utilize multipart/form-data with other different embeddable content types like images. You can read about this in more detail here.

We used this most basic of patterns to expand into other actions like pulling down HTML from URLs to create an auto-snipper, inserting an image URL into a normal note with img tags, or wrapping up some normal text content into some valid HTML.

Each variation took maybe 15-20 minutes to build and test, but in the end we had a pretty robust little app that was very painless to develop!

Launch!

A mere 3 hours after learning of the OneNote API, we were able to launch our OneNote integration, which is a testament to a knockout combination: the great team behind the OneNote API and the Zapier Developer Platform.

Bryan Helmig is a co-founder and engineer at Zapier. In addition to being a blue/jazz guitarist and whiskey connoisseur, he's hacked on just about every API available today and has helped design and build the Zapier platform which makes 10s of millions of API calls a day.