Tutorial: use the apigee.com interactive REST console
Learn how to create REST requests using the apigee.com console for the Microsoft OneNote API.
Last modified: October 27, 2014
Applies to: OneNote service
There is often no better way to learn a new API than to play around with it using an interactive console. Likewise, having an interactive console can often make debugging easier, when you can't figure out whether it's your code, the request, or the API that's causing the problem. To help in all those cases, we worked with the apigee.com engineers to make the Microsoft OneNote API available in an intuitive, interactive web-based console. Use this tutorial to create a simple REST call to the OneNote API.
The URL for the console is: https://apigee.com/onenote/embed/console/onenote
Below is a screenshot of the console after a successful POST request. As we add more features to the API, the console will have more things to try and learn about.
The primary things you'll use right now are:
Authentication drop-down (top) lets you enter credentials for the Microsoft account where the OneNote notebook pages are created.
API method slide-out (left side) lets you choose from the default methods. Right now, only the Create Page request is available.
Body tab (middle) is where you enter the data you want to post. The default data performs a multi-part POST with some simple HTML. When you're on the body tab, scroll down in the tab area…there are useful settings farther down in that middle section.
Send button, because that's where the good stuff happens.
Request and Response panels show exactly what was sent, and exactly what came back.
When you first visit the interactive API console, log in with your Microsoft Account.
Choose the drop-down on the Authentication section and select OAuth 2 Implicit Grant.
Choose the wide orange Sign in with OneNote button to sign in with your credentials.
When the window opens, enter your Microsoft account credentials and choose Sign in.
Confirm to allow the OneNote API to create new pages in OneNote. Choose Yes.
Now, start sending requests to the API, and creating new pages in your OneNote notebook stored in OneDrive.
The console should now look like this, with the Authentication box showing "onenote-AuthenticatedUser".
Use the following steps to create your first request using the console.
Choose the API method fly-out to reveal the list of available API methods. Currently, there's only the one Create Page POST method. Select the Create Page method to populate the message headers and body with some simple HTML.
When you start creating requests, you'll spend most of your time on the Body tab, because most of the complexity in posting a new page comes from what you're posting. Choose the Body tab, and use the scroll-bar on the far right side to see the full list of body properties.
Look at the Text field of the Body. It contains a single part named Presentation, with some simple HTML. You can change the HTML using information from the OneNote API HTML tag support page. When you are ready, choose the Send button. While the OneNote API processes your request, you'll see a progress indicator.
When the request finishes processing, the console displays the results, which we'll go over next.
After the request completes, the console shows the Request you sent on the left, and the Response from the OneNote API on the right, like below.
Read those carefully. If you're working directly with the API in the REST format, you'll find lots of things telling you what's going on. In the example above, be aware of the HTTP status 201 Created. This is the normal status returned when the page creation request completed successfully.
To get the full benefit of the console, be sure to use it as you read through the OneNote API reference. For REST-based snippets that accomplish specific things, go through the Develop with the OneNote API topics and give them a try. Learning the OneNote API can be quick, easy, and fun using the apigee interactive console.