HTML in the OneNote API
Hi, Gareth Jones here - I'm the API architect for our spangly new OneNote service and I wanted to take a bit of time to talk about using HTML to create OneNote pages.
First a little bit of context - we started out building an object model that let you put content in a OneNote page with a bunch of options for simple text, rich html text and images, but we didn't find a nice solution that met our primary goal of a really simple experience for creating pages that would scale out later for retrieving pages, updating them and other common operations.
So we took a little step back, and realized that the way the world already creates and lays out pages is HTML5. (You know, as used on that internet thing you've heard so much about.)
As it turns out, HTML5 and OneNote are a great fit. Most things you can put on a OneNote page can be described pretty crisply with totally standard HTML constructs, formatted text, images, tables, titles. It's super simple to POST a chunk of well-formed HTML to our pages endpoint, https://www.onenote.com/api/1.0/pages to get up and running.
<html>
<head>
<title>OneNote Haiku</title>
</head>
<body>
<p>Many years OneNote had clients<br />
Now in spring<br />
An API rises</p>
</body>
</html>
Of course, OneNote isn't actually a web browser, and doesn't have quite such a free-form page layout model as the web, so we support a subset of HTML5. Also, as we're not an interactive browser, we don't support things like scripts, and right now we don't support linked style sheets. For a full description of what works, hop over to our docs here, but as a rough guide, most basic tags work well, and tables are the best way to lay out more complex content on a OneNote page.
There's a few really great extras that we support that we were able to fit nicely into our API using the standard extensibility mechanisms that are built in to HTML5.
You can quickly get a snapshot of any web site into your OneNote page, using an extension attribute on an <img> tag, called 'data-render-src'. Here's an example.
…
<img data-render-src="https://stackoverflow.com/questions/tagged/onenote" alt="Stack Overflow" />
…
Of course, like all images in OneNote, we'll do OCR, so all the text will be searchable.
We'll go and fetch images from the internet for you, but if you need to create pages with images that aren't available on the public web, you can send them to us along with your request. You'll just need to wrap your html in a multipart mime envelope, and add the images as extra parts, then send us the whole thing in your POST. Take a look at the docs here for more details. You can find a multipart MIME library for most platforms to make this really simple, for example, on iOS, we've been using AFNetworking. It's built in to the .net framework on Microsoft platforms.
You then just use our custom uri scheme, 'name:<part-name>' to reference the image in your tags, like this:
…
<img src="name:MyAstonishingImagePart" alt="Wow, this is a great picture of a cat wearing Yoda ears!" />
…
Overall, we're really pleased with our choice to use HTML5 and we think you'll find it really easy to create pages just as you want them, in a way that's fast and natural to anyone that's ever written a web page.
Let us know what you think and which tags and styles you want supported next in the comments or @onenotedev
Gareth