|
| 1 | +# iOS-REST-API-Explorer |
| 2 | +OneNote REST API Explorer for iOS |
| 3 | + |
| 4 | +**Table of contents** |
| 5 | + |
| 6 | +* [Introduction](#introduction) |
| 7 | +* [Change History](#change-history) |
| 8 | +* [Prerequisites](#prerequisites) |
| 9 | +* [Set Up Your Environment](#set-up-your-environment) |
| 10 | +* [Understand the code](#understand-the-code) |
| 11 | +* [Questions and comments](#questions-and-comments) |
| 12 | +* [Additional resources](#additional-resources) |
| 13 | + |
| 14 | + |
| 15 | + |
| 16 | +**Introduction** |
| 17 | + |
| 18 | +The OneNote REST API Explorer for iOS explores the simple REST calls that access, add, update, and delete OneNote entities such as notebooks, section groups, sections, and pages. The app lets you authenticate against an Office 365 tenant and perform standard operations against the OneNote service in O365. |
| 19 | + |
| 20 | +This sample includes the following operations for enterprise OneNote: |
| 21 | + |
| 22 | +**Notebook** |
| 23 | + |
| 24 | +* Get a list of your noteobooks |
| 25 | +* Get notebooks and expand notebook sections |
| 26 | +* Get a notebook by id |
| 27 | +* Get metadata for a notebook |
| 28 | +* Get notebooks by name |
| 29 | +* Get a sorted list of notebooks with metadata |
| 30 | +* Create a new notebook |
| 31 | + |
| 32 | +**Section group** |
| 33 | + |
| 34 | +* Get a list of section groups |
| 35 | +* Get a list of all section groups in a notebook |
| 36 | + |
| 37 | +**Sections** |
| 38 | + |
| 39 | +* Get a list of sections in a notebook |
| 40 | +* Get a list of all sections |
| 41 | +* Get sections with a specific name |
| 42 | +* Get metadata of a section |
| 43 | +* Get sections by name |
| 44 | +* Get metadata for a section |
| 45 | +* Create a section |
| 46 | + |
| 47 | +**Pages** |
| 48 | + |
| 49 | +* Post a simple page with HTML content |
| 50 | +* Post a page with an embedded image |
| 51 | +* Get pages with a specific title |
| 52 | +* Post a page with a snapshot of a web page |
| 53 | +* Delete a page |
| 54 | +* Append text to a page |
| 55 | +* Post a page with an Url snapshot |
| 56 | +* Get the pages in a section |
| 57 | +* Post pages with rendered attachments |
| 58 | +* Post a page with note tags |
| 59 | +* post a page with business card image text |
| 60 | +* Post a page with extracted web page text |
| 61 | +* Get a list of all pages |
| 62 | +* Get a paged list of pages |
| 63 | +* Get a sorted list of pages |
| 64 | +* Get the HTML contents of a page |
| 65 | + |
| 66 | +**Note:** Currently this sample does not support MSA authentication with accounts such as outlook.com or a live account. This functionality will be included in future updates. |
| 67 | + |
| 68 | + |
| 69 | +##Change History |
| 70 | +July 2015: |
| 71 | +* Initial release |
| 72 | + |
| 73 | + |
| 74 | +##Prerequisites |
| 75 | +* [Xcode](https://developer.apple.com/) from Apple. |
| 76 | +* An Office 365 account. You can get an Office 365 account by signing up for an [Office 365 Developer site](http://msdn.microsoft.com/library/office/fp179924.aspx). This will give you access to the APIs that you can use to create apps that target Office 365 data. |
| 77 | +* A Microsoft Azure tenant to register your application. Azure Active Directory provides identity services that applications use for authentication and authorization. A trial subscription can be acquired here: [Microsoft Azure](https://account.windowsazure.com/SignUp). |
| 78 | + |
| 79 | +**Important**: You will also need to ensure your Azure subscription is bound to your Office 365 tenant. To do this see the Active Directory team's blog post, [Creating and Managing Multiple Windows Azure Active Directories](http://blogs.technet.com/b/ad/archive/2013/11/08/creating-and-managing-multiple-windows-azure-active-directories.aspx). The section **Adding a new directory** will explain how to do this. You can also read [Set up Azure Active Directory access for your Developer Site](http://msdn.microsoft.com/office/office365/howto/setup-development-environment#bk_CreateAzureSubscription) for more information. |
| 80 | + |
| 81 | + |
| 82 | +* Installation of [CocoaPods](https://cocoapods.org/) as a dependency manager. CocoaPods will allow you to pull the required dependencies into the project. |
| 83 | + |
| 84 | + |
| 85 | +* A registered Azure application with a client id and redirect uri value. This procedure will be discussed in below section **Register your app with Microsoft Azure.** |
| 86 | + |
| 87 | + |
| 88 | + |
| 89 | +##Set Up Your Environment |
| 90 | +Once you have an Office 365 account, an Azure AD account that is bound to your Office 365 Developer site, you'll need to perform the following steps: |
| 91 | + |
| 92 | +1. Install and use CocoaPods to get the required dependencies into your project. We'll show you how to do later in the section **Use CocoaPods to import the required dependencies**. |
| 93 | +2. Register your application with Microsoft Azure, and configure the appropriate OneNote permissions. |
| 94 | +3. Enter the Azure app registration specifics (ClientID and RedirectUri) into the OneNote REST API Explorer for iOS app. |
| 95 | + |
| 96 | +## Use CocoaPods to import the required dependencies |
| 97 | +Note: If you've never used CocoaPods before as a dependency manager you'll have to install it prior to getting the dependencies into your project. If you already have it installed you may skip this installation step and move on to **Getting the iOS dependencies in your project**. |
| 98 | + |
| 99 | +Enter both these lines of code from the **Terminal** app on your Mac. |
| 100 | + |
| 101 | + sudo gem install cocoapods |
| 102 | + pod setup |
| 103 | + |
| 104 | +If the install and setup were successful, you should see the message **Setup completed in Terminal**. For more information on CocoaPods, and its usage, see [CocoaPods](https://cocoapods.org/). |
| 105 | + |
| 106 | + |
| 107 | +**Getting the iOS dependencies in your project.** |
| 108 | +The iOS-OneNote-REST Explorer sample has a dependency on the Active Directory Authentication Library for iOS (ADAL) for enabling client to access OneNote for enterprise notebooks. The ADAL provides protocol support for OAuth2, Web API integration with user level consent, and two-factor authentication. It also uses AFNetworking to help manage REST communication between the app and the OneNote service. The sample contains a podfile that will get the ADAL and AFNetworking components (pods) into your project. It's located in the root ("Podfile"). The syntax should look something similar to this: |
| 109 | + |
| 110 | + |
| 111 | + pod "AFNetworking", "~> 2.0" |
| 112 | + pod 'ADALiOS', "~> 1.2.4" |
| 113 | + |
| 114 | + |
| 115 | + |
| 116 | +You'll simply need to navigate to the project directory in the **Terminal** (root of the project folder) and run the following command. |
| 117 | + |
| 118 | + |
| 119 | + pod install |
| 120 | + |
| 121 | +Note: You should receive confirmation that these dependencies have been added to the project. If there is a syntax error in the Podfile, you will encounter an error when you run the install command. |
| 122 | + |
| 123 | +## Register your app with Microsoft Azure |
| 124 | +1. Sign in to the [Azure Management Portal](https://manage.windowsazure.com), using your Azure AD credentials. |
| 125 | +2. Click **Active Directory** on the left menu, then select the directory for your Office 365 developer site. |
| 126 | +3. On the top menu, click **Applications**. |
| 127 | +4. Click **Add** from the bottom menu. |
| 128 | +5. On the **What do you want to do page**, click **Add an application my organization is developing**. |
| 129 | +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. |
| 130 | +7. Click the arrow icon on the bottom-right corner of the page. |
| 131 | +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**. |
| 132 | +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. |
| 133 | +10. Under **permissions to other applications**, select **Add application.** Select OneNote and then the check box to proceed. |
| 134 | +11. For the **OneNote** application add the following permissions: |
| 135 | + * View and modify OneNote notebooks in your organization |
| 136 | + * View and modify OneNote notebooks |
| 137 | + * Create pages in OneNote notebooks |
| 138 | + |
| 139 | + |
| 140 | +12. For the **Windows Azure Active Directory** application add or make sure the following permissions are enabled: |
| 141 | + * Enable sign-on and read users' profiles |
| 142 | + * Access your organization's directory |
| 143 | + |
| 144 | +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**. |
| 145 | +14. Click **Save** in the bottom menu. |
| 146 | + |
| 147 | + |
| 148 | + |
| 149 | + |
| 150 | +## Get the Client ID and Redirect Uri into the project |
| 151 | + |
| 152 | +Finally you'll need to add the Client ID and Redirect Uri you recorded from the previous section **Register your app with Microsoft Azure**. |
| 153 | + |
| 154 | +Browse the **iOS-REST-API-Explorer** project directory and open up the workspace (iOS-REST-API-Explorer). In the **O365Auth.m** file you'll see that the **ClientID** and **RedirectUri** values can be added to the top of the file. Supply the necessary values here: |
| 155 | + |
| 156 | + // You will set your application's clientId and redirect URI. You get |
| 157 | + // these when you register your application in Azure AD. |
| 158 | + static NSString * const REDIRECT_URL_STRING = @"ENTER_REDIRECT_URI_HERE"; |
| 159 | + static NSString * const CLIENT_ID = @"ENTER_CLIENT_ID_HERE"; |
| 160 | + static NSString * const AUTHORITY = @"https://login.microsoftonline.com/common"; |
| 161 | + |
| 162 | + |
| 163 | + |
| 164 | +##Understand the code |
| 165 | +The REST API Explorer for iOS project uses these classes to manage interactions with OneNote for Enterprise. |
| 166 | + |
| 167 | +###Sample project organization |
| 168 | + |
| 169 | +This sample demonstrates OneNote REST calls across the notebook, pages, sections, and section groups entities in O365. We use the Master-Detail app template in Xcode as a base. There are three primary sections of interest in the sample hierarchy: |
| 170 | + |
| 171 | +- **Authentication (located in Library/Authentication)** - The OneNote API for iOS uses the Azure Active Directory Library (ADAL) for iOS for connecting your app to Office 365. The ADAL provides protocol support for OAuth2, Web API integration with user level consent, and two-factor authentication. The REST API Explorer uses the ADAL library to authenticate a user who wants to access OneNote for enterprise notebooks. The **Authentication** folder classes Authentication Manager and O365Auth that are responsible for authenticating the app to Office 365. Although not supported in this release, the code for authenticating with Microsoft Accounts (office.com, live.com) will be added in a future release. |
| 172 | + |
| 173 | +- **OneNote Operations (located in OneNoteOperations)** - The class **OneNoteManager** is the library of REST operations that can be performed in this sample against OneNote (GET, POST, DELETE, and PATCH). We've also created an **Operations class (Operation.h/Operation.m)** that represents a single REST operation - it captures the operation name, REST URL, and other metadata. |
| 174 | + |
| 175 | +- **Networking (located in Network)** - This sample uses the [AFNetworking](https://github.com/AFNetworking/AFNetworking) library for REST operations that will be downloaded with the pod install. See the class **NetworkManager** for the construction of each type of request. |
| 176 | + |
| 177 | + |
| 178 | +## Additional resources |
| 179 | + |
| 180 | +* [OneNote APIs documentation](https://msdn.microsoft.com/en-us/library/office/dn575420.aspx) |
| 181 | +* [OneNote developer center](http://dev.onenote.com/) |
| 182 | +* [Microsoft Office 365 API Tools](https://visualstudiogallery.msdn.microsoft.com/a15b85e6-69a7-4fdf-adda-a38066bb5155) |
| 183 | +* [Office Dev Center](http://dev.office.com/) |
| 184 | +* [Office 365 APIs starter projects and code samples](http://msdn.microsoft.com/en-us/office/office365/howto/starter-projects-and-code-samples) |
| 185 | + |
| 186 | + |
| 187 | +## Copyright |
| 188 | +Copyright (c) 2015 Microsoft. All rights reserved. |
| 189 | + |
0 commit comments