Android-REST-API-Explorer

Build Status

Table of contents

Looking to build cool apps that help people work with their OneNote notebooks? Explore, learn, and understand the OneNote REST APIs by using the OneNote REST API Explorer for Android. This sample lets you view and run the REST APIs that read, add, update, and delete OneNote entities such as notebooks, section groups, sections, and pages. The app lets you authenticate in two ways. You can authenticate using a Microsoft Account (MSA) to connect to OneNote on your personal OneDrive. Or you can authenticate using a work or school account to connect to OneNote on your organization's OneDrive for Business on Office 365.

You can explore the following operations for OneNote:

Notebook

Section group

Sections

Pages

Change History

August 2015

July 2015:

Device requirements

To run the REST Explorer project, your device must meet the following requirements:

Prerequisites

To use the OneNote REST API Explorer for Android, you need the following:

Azure client application registration

  1. Sign in to the Azure Management Portal, using your Azure AD credentials.

  2. Click Active Directory on the left menu, then select the directory for your Office 365 developer site.

  3. On the top menu, click Applications.

  4. Click Add from the bottom menu.

  5. On the What do you want to do page, click Add an application my organization is developing.

  6. On the Tell us about your application page, specify OneNote REST API Explorer for the application name and select NATIVE CLIENT APPLICATION for type.

  7. Click the arrow icon on the bottom-right corner of the page.

  8. On the Application information page, specify a Redirect URI, for this example, you can specify http://localhost/OneNoteRESTExplorer, and then select the checkbox in the lower-right hand corner of the page. Remember this value for the below section Getting the ClientID and RedirectUri into the project.

  9. Once the application has been successfully added, you will be taken to the Quick Start page for the application. From here, select Configure in the top menu.

  10. Under permissions to other applications, select Add application. Select OneNote and then the check box to proceed.

  11. For the OneNote application add the following permissions:

    • View and modify OneNote notebooks in your organization
    • View and modify OneNote notebooks
    • Create pages in OneNote notebooks Choose OneNote permissions required for your application.
  12. For the Windows Azure Active Directory application add or make sure the following permissions are enabled:

    • Enable sign-on and read users' profiles
    • Access your organization's directory Choose Azure Active Directory permissions required for your application.
  13. Copy the value specified for Client ID on the Configure page. Remember this value for the below section Getting the ClientID and RedirectUri into the project.

  14. Click Save in the bottom menu.

Microsoft account application registration

  1. Go to the Windows Live application management site.

  2. Sign in by using your Windows Live ID.

    Note: If this is your first visit to this site, you will see several pages that configure your Windows Live ID for use with the site.

  3. Click Create application.

  4. Enter a unique application name. If you agree to the terms, click Accept.

  5. There are many settings for your app, but to make it work with this sample, you need to make the following changes:

    1. On API Settings, set the Mobile or desktop client app field to Yes.
    2. On API Settings, set the Redirect URLs field to a valid URL. The URL does not need to reference an actual location, but it must be a valid URL.
  6. Once you are satisfied with your app settings, click Save.

  7. Click App Settings. This will display a page with your client id. You will use this value later when configuring your project.

Configure the project

  1. Download or clone the OneNote REST API Explorer for Android.
  2. Start Android Studio.
  3. From the Welcome to Android Studio dialog box, choose Import project (Eclipse ADT, Gradle, etc).
  4. Select the settings.gradle file in the Android-REST-API-Explorer folder and click OK.
  5. Respond to the dialog ("Gradle Sync: Gradle settings for this project are not configured yet. Would you like the project to use the Gradle wrapper? ") by clicking the OK button to use the Gradle wrapper.
  6. Open the ServiceConstants.java file in the com.microsoft.o365_android_onenote_rest.conf package.
  7. Find the CLIENT_ID string and set its value to the client id you registered in Azure.
  8. Find the REDIRECT_URI string and set its value to the redirect URI you registered in Azure.
  9. Find the MSA_CLIENT_ID string and set its value to the client id you registered for your app in your Microsoft Account.

Run the project

Once you've built the REST Explorer project you can run it on an emulator or device.

  1. Run the project.

  2. Click the authentication account that you want to sign in to.

  3. Enter your credentials.

  4. Click a REST operation in the main activity to show operation details.

    Note: Some operations require input before they will run. For example, to update a page, you must first select a page to update. On these operations there will be a spinner, or text box, to select or enter required input for an operation.

  5. Click the run button to start the REST operation and wait for the operation to finish.

  6. Click in the Response Headers or Response Body text boxes to copy the box contents to the emulator/device clipboard.

  7. Click the Back button on the REST Explorer toolbar to return to the REST operation list.

  8. (Optional) Click the overflow menu to get the Disconnect menu option.

Understand the code

The REST API Explorer project uses these classes to manage interactions with OneNote for Enterprise and consumer OneNote:

Sample project organization

The REST API explorer project is comprised of four modules. The modular design allows you to add authentication and OneNote REST API support to your app by importing modules from REST API Explorer into your app. After you've imported the modules, use the code in the REST API Explorer app module as an example of how to call methods in the other sample modules.

REST API Explorer modules

Snippet classes

A snippet runs a single REST operation and returns the results. Snippets are found in the app module. Snippets set the state required to make the calls on the OneNote service classes described below. Where necessary, a snippet class gets the notebooks, sections, or pages to load the spinner control shown on the snippet detail fragment for a given REST operation.

OneNote API service classes

These classes are found in the onenoteapi module and make the Retrofit library calls that generate the REST queries and handle operation results. These service classes are consumed by the snippets.

Value object classes

These classes are found in the onenotevos module. The value object classes describe JSON payloads as objects.

Authentication classes for Office 365 business accounts

The authentication classes are found in the O365-Auth module. These classes use the Microsoft Azure Active Directory Library (ADAL) for Android to connect to a business version of Office 365 such as Office 365 Enterprise.

Authentication for Office 365 personal accounts

Authentication for logging in with a Microsoft Account to a personal version of Office 365 such as Office 365 Home is handled by the MSA Auth for Android library. The app uses the LiveAuthClient class to connect and disconnect.

Screenshots

Login REST Call List
Login screen REST call list page
REST Call Detail Create Page
REST call detail page Create Page

Questions and comments

We'd love to get your feedback about the OneNote REST API Explorer for Android sample. You can send your feedback to us in the Issues section of this repository.
General questions about Office 365 development should be posted to Stack Overflow. Make sure that your questions are tagged with [Office365] and [API].

Contributing

You will need to sign a Contributor License Agreement before submitting your pull request. To complete the Contributor License Agreement (CLA), you will need to submit a request via the form and then electronically sign the CLA when you receive the email containing the link to the document.

Additional resources

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Copyright

Copyright (c) 2015 Microsoft. All rights reserved.