Skip to content

ReadMe - Adding table of contents #416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nikithauc merged 6 commits into from
Apr 7, 2021
Merged

ReadMe - Adding table of contents #416

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0ea910b
creating table of contents
nikithauc Apr 1, 2021
cfd8ae0
CreateClient md changes, more links in toc
nikithauc Apr 6, 2021
385b058
Adding additional resources
nikithauc Apr 6, 2021
7da8998
Removing travis badge
nikithauc Apr 6, 2021
80159dc
Apply suggestions from code review
nikithauc Apr 7, 2021
311d14f
replace - with :
nikithauc Apr 7, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 61 additions & 65 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,40 @@
# Microsoft Graph JavaScript Client Library

[![npm version badge](https://img.shields.io/npm/v/@microsoft/microsoft-graph-client.svg?maxAge=86400)](https://www.npmjs.com/package/@microsoft/microsoft-graph-client) [![Travis](https://travis-ci.org/microsoftgraph/msgraph-sdk-javascript.svg?maxAge=86400)](https://travis-ci.org/microsoftgraph/msgraph-sdk-javascript) [![Known Vulnerabilities](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript/badge.svg?maxAge=86400)](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript) [![Licence](https://img.shields.io/github/license/microsoftgraph/msgraph-sdk-javascript.svg)](https://github.com/microsoftgraph/msgraph-sdk-javascript) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/microsoftgraph/msgraph-sdk-javascript) [![Downloads](https://img.shields.io/npm/dm/@microsoft/microsoft-graph-client.svg?maxAge=86400)](https://www.npmjs.com/package/@microsoft/microsoft-graph-client)
[![npm version badge](https://img.shields.io/npm/v/@microsoft/microsoft-graph-client.svg?maxAge=86400)](https://www.npmjs.com/package/@microsoft/microsoft-graph-client) [![Known Vulnerabilities](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript/badge.svg?maxAge=86400)](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript) [![Licence](https://img.shields.io/github/license/microsoftgraph/msgraph-sdk-javascript.svg)](https://github.com/microsoftgraph/msgraph-sdk-javascript) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/microsoftgraph/msgraph-sdk-javascript) [![Downloads](https://img.shields.io/npm/dm/@microsoft/microsoft-graph-client.svg?maxAge=86400)](https://www.npmjs.com/package/@microsoft/microsoft-graph-client)

The Microsoft Graph JavaScript client library is a lightweight wrapper around the Microsoft Graph API that can be used server-side and in the browser.

**Looking for IntelliSense on models (Users, Groups, etc.)? Check out the [Microsoft Graph Types](https://github.com/microsoftgraph/msgraph-typescript-typings) repository!**
- [Microsoft Graph JavaScript Client Library](#microsoft-graph-javascript-client-library)
- [Installation](#installation)
- [Via npm](#via-npm)
- [Via Script Tag](#via-script-tag)
- [Getting started](#getting-started)
- [1. Register your application](#1-register-your-application)
- [2. Create a Client Instance](#2-create-a-client-instance)
- [3. Make requests to the graph](#3-make-requests-to-the-graph)
- Documentation
- [HTTP Actions](docs/Actions.md)
- [Chained APIs to call Microsoft Graph](docs/CallingPattern.md)
- [OData system query options - Query Parameters](docs/QueryParameters.md)
- [Batch multiple requests into single HTTP request](docs/content/Batching.md)
- [Configurations to your request](docs/OtherAPIs.md)
- [Query](docs/OtherAPIs.md#QUERY)
- [Version](docs/OtherAPIs.md#VERSION)
- [Headers](docs/OtherAPIs.md#HEADER-AND-HEADERS)
- [Options](docs/OtherAPIs.md#OPTION-AND-OPTIONS)
- [MiddlewareOptions](docs/OtherAPIs.md#MIDDLEWAREOPTIONS)
- [ResponseType](docs/OtherAPIs.md#RESPONSETYPE)
- [Upload large files to OneDrive, Outlook, Print API](docs/tasks/LargeFileUploadTask.md)
- [Page Iteration](docs/tasks/PageIterator.md)
- [Getting Raw Response](docs/GettingRawResponse.md)
- [Creating an instance of TokenCredentialAuthenticationProvider](docs/TokenCredentialAuthenticationProvider.md)
- [Questions and comments](#questions-and-comments)
- [Contributing](#contributing)
- [Additional resources](#additional-resources)
- [Third Party Notices](#third-party-notices)
- [Security Reporting](#security-reporting)
- [License](#license)
- [We Value and Adhere to the Microsoft Open Source Code of Conduct](#we-value-and-adhere-to-the-microsoft-open-source-code-of-conduct)

[![TypeScript demo](https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-javascript/master/types-demo.PNG)](https://github.com/microsoftgraph/msgraph-typescript-typings)

Expand All @@ -16,10 +46,16 @@ The Microsoft Graph JavaScript client library is a lightweight wrapper around th
npm install @microsoft/microsoft-graph-client
```

import `@microsoft/microsoft-graph-client` into your module and also you will need polyfills for fetch like [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch).
import `@microsoft/microsoft-graph-client` into your module.

Also, you will need to import any fetch polyfill which suits your requirements.
Following are some fetch polyfills -
* [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch).
* [cross-fetch](https://www.npmjs.com/package/cross-fetch)
* [whatwg-fetch](https://www.npmjs.com/package/whatwg-fetch)

```typescript
import "isomorphic-fetch";
import "isomorphic-fetch"; // or import the fetch polyfill you installed
import { Client } from "@microsoft/microsoft-graph-client";
```

Expand All @@ -45,60 +81,25 @@ In case your browser doesn't have support for [Fetch](https://developer.mozilla.
```

## Getting started

### 1. Register your application

Register your application to use Microsoft Graph API using one of the following supported authentication portals:

- [Microsoft Application Registration Portal](https://apps.dev.microsoft.com): Register a new application that works with Microsoft Accounts and/or organizational accounts using the unified V2 Authentication Endpoint.
- [Microsoft Azure Active Directory](https://manage.windowsazure.com): Register a new application in your tenant's Active Directory to support work or school users for your tenant or multiple tenants.

### 2. Authenticate for the Microsoft Graph service

The Microsoft Graph JavaScript Client Library has an adapter implementation for the following -

- ([TokenCredentialAuthenticationProvider](src/authentication/TokenCredentialAuthenticationProvider.ts)) to support [Azure Identity TokenCredential](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md) (Azure Identity client library for JavaScript) which takes care of getting the `accessToken`. @azure/identity library does not ship with this library, user has to include it externally (For including @azure/identity, refer [this](https://www.npmjs.com/package/@azure/identity)).

> Learn how to [create an instance of TokenCredentialAuthenticationProvider](./docs/TokenCredentialAuthenticationProvider.md).

- ([ImplicitMSALAuthenticationProvider](src/ImplicitMSALAuthenticationProvider.ts)) for [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core) (Microsoft Authentication Library) which takes care of getting the `accessToken`. MSAL library does not ship with this library, user has to include it externally (For including MSAL, refer [this](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core#installation)).

> Learn how to [create an instance of ImplicitMSALAuthenticationProvider](./docs/ImplicitMSALAuthenticationProvider.md).

User can integrate own preferred authentication library by implementing `IAuthenticationProvider` interface. Refer implementing [Custom Authentication Provider](./docs/CustomAuthenticationProvider.md).

### 3. Initialize a Microsoft Graph Client object with an authentication provider

An instance of the **Client** class handles requests to Microsoft Graph API and processing the responses. To create a new instance of this class, you need to provide an instance of [`IAuthenticationProvider`](src/IAuthenticationProvider.ts) which needs to be passed as a value for `authProvider` key in [`ClientOptions`](src/IClientOptions.ts) to a static initializer method `Client.initWithMiddleware`.
To call Microsoft Graph, your app must acquire an access token from the Microsoft identity platform.
Learn more about this -
- [Authentication and authorization basics for Microsoft Graph](https://docs.microsoft.com/en-us/graph/auth/auth-concepts)
- [Register your app with the Microsoft identity platform](https://docs.microsoft.com/en-us/graph/auth/auth-concepts)

#### For browser environment
### 2. Create a Client Instance

```typescript
const options = {
authProvider, // An instance created from previous step
};
const Client = MicrosoftGraph.Client;
const client = Client.initWithMiddleware(options);
```

#### For node environment

```typescript
import { Client } from "@microsoft/microsoft-graph-client";
The Microsoft Graph client is designed to make it simple to make calls to Microsoft Graph. You can use a single client instance for the lifetime of the application.

const options = {
authProvider, // An instance created from previous step
};
const client = Client.initWithMiddleware(options);
```
For information on how to create a client instance, see [Creating Client Instance](./docs/CreatingClientInstance.md)

For more information on initializing client, refer [this document](./docs/CreatingClientInstance.md).

### 4. Make requests to the graph
### 3. Make requests to the graph

Once you have authentication setup and an instance of Client, you can begin to make calls to the service. All requests should be start with `client.api(path)` and end with an [action](./docs/Actions.md).
Once you have authentication setup and an instance of Client, you can begin to make calls to the service. All requests should start with `client.api(path)` and end with an [action](./docs/Actions.md).

Getting user details
Getting user details -
Copy link
Contributor

@zengin zengin Apr 6, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: what is the trailing - sign for?

Copy link
Contributor Author

@nikithauc nikithauc Apr 7, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indicating the the following sample is for Getting user details


```typescript
try {
Expand All @@ -109,7 +110,7 @@ try {
}
```

Sending an email to the recipients
Sending an email to the recipients -
Copy link
Contributor

@zengin zengin Apr 6, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here


```typescript
// Construct email object
Expand Down Expand Up @@ -137,16 +138,6 @@ try {

For more information, refer: [Calling Pattern](docs/CallingPattern.md), [Actions](docs/Actions.md), [Query Params](docs/QueryParameters.md), [API Methods](docs/OtherAPIs.md) and [more](docs/).

## Documentation

- [Batching](docs/content/Batching.md)
- [Large File Upload Task](docs/tasks/LargeFileUploadTask.md)
- [Page Iterator](docs/tasks/PageIterator.md)
- [Actions](docs/Actions.md)
- [Query Parameters](docs/QueryParameters.md)
- [Other APIs](docs/OtherAPIs.md)
- [Getting Raw Response](docs/GettingRawResponse.md)

## Questions and comments

We'd love to get your feedback about the Microsoft Graph JavaScript client library. You can send your questions and suggestions to us in the [Issues](https://github.com/microsoftgraph/msgraph-sdk-javascript/issues) section of this repository.
Expand All @@ -157,11 +148,16 @@ Please see the [contributing guidelines](CONTRIBUTING.md).

## Additional resources

- [Microsoft Graph website](https://graph.microsoft.io)
- [Microsoft Graph TypeScript types](https://github.com/microsoftgraph/msgraph-typescript-typings/)
- [Build Angular single-page apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-angularspa)
- [Build Node.js Express apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-nodeexpressapp)
- [Office Dev Center](http://dev.office.com/)
- [Microsoft Graph website](https://graph.microsoft.io)

- The Microsoft Graph TypeScript definitions enable editors to provide intellisense on Microsoft Graph objects including users, messages, and groups.
- [@microsoft/microsoft-graph-types](https://www.npmjs.com/package/@microsoft/microsoft-graph-types) or [@types/microsoft-graph](https://www.npmjs.com/package/@types/microsoft-graph)
- [@microsoft/microsoft-graph-types-beta](https://www.npmjs.com/package/@microsoft/microsoft-graph-types-beta)
- [Build React Native apps with Microsoft Graph](https://docs.microsoft.com/en-us/graph/tutorials/react-native)
- [Build Angular single-page apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-angularspa)
- [Build Node.js Express apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-nodeexpressapp)
- [Microsoft Graph Toolkit: UI Components and Authentication Providers for Microsoft Graph](https://docs.microsoft.com/en-us/graph/toolkit/overview)
- [Office Dev Center](http://dev.office.com/)

## Third Party Notices

Expand Down
51 changes: 30 additions & 21 deletions docs/CreatingClientInstance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,35 +4,43 @@ Initialization of the Client can be done in one of below two ways

## 1. Create With ClientOptions [Recommended]

The Microsoft Graph SDK client configures a default set of middleware that allows the SDK to communicate with the Microsoft Graph endpoints. This default set is customizable, allowing you to change the behavior of the client

In order to instantiate a Client object, one has to pass in the `authProvider` or `middleware` chain in [ClientOptions](../src/IClientOptions.ts).

### Option A. Default Middleware chain

Pass an instance of a class which implements [AuthenticationProvider](../src/IAuthenticationProvider.ts) interface as `authProvider` in [ClientOptions](../src/IClientOptions.ts), which will instantiate the Client with default set of middleware chain.
The default middleware chain contains consecutively chained instances of the following -
- [AuthenticationHandler](../src/middleware/AuthenticationHandler.ts)
- [RetryHandler](../src/middleware/RetryHandler.ts)
- [RedirectHandler](../src/middleware/RedirectHandler.ts)
- [TelemetryHandler](../src/middleware/TelemetryHandler.ts)
- [HTTPMessageHandler](../src/middleware/HTTPMessageHandler.ts)

Library is shipped with one such authentication provider named [ImplicitMSALAuthenticationProvider](../src/ImplicitMSALAuthenticationProvider.ts). This ImplicitMSALAuthenticationProvider depends on an authentication library [msal.js](https://github.com/AzureAD/microsoft-authentication-library-for-js) which is not shipped along with the library, one has to externally include msal.js to use ImplicitMSALAuthenticationProvider.
To create a client instance with the default middleware chain -

```typescript
// Instantiating Client with ImplicitMSALAuthenticationProvider
1. Create an instance of a class which implements [AuthenticationProvider](../src/IAuthenticationProvider.ts) interface. This class should contain the logic to get the access token to be passed to the Microsoft Graph API.

// An Optional options for initializing the MSAL @see https://github.com/AzureAD/microsoft-authentication-library-for-js/wiki/MSAL-basics#configuration-options
const msalConfig = {
auth: {
clientId: <CLIENT_ID> // Client Id of the registered application
},
};
2. Pass the instance as `authProvider` in [ClientOptions](../src/IClientOptions.ts) to instantiate the Client which will create and set the default middleware chain.

// Important Note: This library implements loginPopup and acquireTokenPopup flow, remember this while initializing the msal
// Initialize the MSAL @see https://github.com/AzureAD/microsoft-authentication-library-for-js#1-instantiate-the-useragentapplication
const msalApplication = new UserAgentApplication(msalConfig);
const options = new MicrosoftGraph.MSALAuthenticationProviderOptions(<SCOPES>); // An array of graph scopes
```typescript
let clientOptions: ClientOptions = {
authProvider: new ImplicitMSALAuthenticationProvider(msalApplication, options)
authProvider: new YourAuthProviderClass(),
};
const client = Client.initWithMiddleware(clientOptions);
```

Want to use own preferred authentication library, for which one has to implement [AuthenticationProvider](../src/IAuthenticationProvider.ts) interface and pass in the instance of it as `authProvider` in [ClientOptions](../src/IClientOptions.ts).
The Microsoft Graph JavaScript Client Library has an adapter implementation for the following -

- ([TokenCredentialAuthenticationProvider](src/authentication/TokenCredentialAuthenticationProvider.ts)) to support [Azure Identity TokenCredential](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md) (Azure Identity client library for JavaScript) which takes care of getting the `accessToken`. @azure/identity library does not ship with this library, user has to include it externally (For including @azure/identity, refer [this](https://www.npmjs.com/package/@azure/identity)).

> Learn how to [create an instance of TokenCredentialAuthenticationProvider](./TokenCredentialAuthenticationProvider.md).

- **DEPRECATED** ([ImplicitMSALAuthenticationProvider](src/ImplicitMSALAuthenticationProvider.ts)) for [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core) (Microsoft Authentication Library) which takes care of getting the `accessToken`. MSAL library does not ship with this library, user has to include it externally (For including MSAL, refer [this](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core#installation)).

> Learn how to [create an instance of ImplicitMSALAuthenticationProvider](./ImplicitMSALAuthenticationProvider.md).

**User can integrate any preferred authentication library by implementing `IAuthenticationProvider` interface**. Refer implementing [Custom Authentication Provider](./CustomAuthenticationProvider.md) for more detailed information.

```typescript
let clientOptions: ClientOptions = {
Expand All @@ -42,11 +50,14 @@ let clientOptions: ClientOptions = {
const client = Client.initWithMiddleware(clientOptions);
```

Refer, [custom authentication provider](./CustomAuthenticationProvider.md) for more detailed information.

### Option B. Custom Middleware chain

Want to have complete control over the request and the response objects, one can provide his own chain of middleware. Have to pass first middleware in the chain as `middleware` in [ClientOptions](../src/IClientOptions.ts).
The Microsoft Graph SDK client allows configuring custom middleware, allowing you to change the behavior of the client. For example, you can insert customized logging, or add a test handler to simulate specific scenarios.

To create a client instance with the custom middleware chain -

1. Refer, [custom middleware chain](./CustomMiddlewareChain.md) for more detailed information.
2. Create the middleware chain and pass first middleware in the chain as `middleware` in [ClientOptions](../src/IClientOptions.ts).

```typescript
let clientOptions: ClientOptions = {
Expand All @@ -56,8 +67,6 @@ let clientOptions: ClientOptions = {
const client = Client.initWithMiddleware(clientOptions);
```

Refer, [custom middleware chain](./CustomMiddlewareChain.md) for more detailed information.

## 2. Create With Options

Pass an [authProvider function](../src/IAuthProvider.ts) in [Options](../src/IOptions.ts) while initializing the Client. In this case, user has to provide his own implementation for getting and refreshing accessToken. A callback will be passed into this authProvider function, accessToken or error needs to be passed in to that callback.
Expand Down
2 changes: 1 addition & 1 deletion docs/OtherAPIs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ try {
You can pass in additional request options through `.option()` and `.options()`, either individually or in a dictionary. Options can be [node specific](https://github.com/bitinn/node-fetch#options) or [from fetch standard](https://fetch.spec.whatwg.org/#requestinit)

```typescript
let HttpProxyAgent = require('http-proxy-agent');
let HttpProxyAgent = require('https-proxy-agent');
try {
// HTTP/HTTPS proxy to connect to
let proxy = <YOUR PROXY>;
Expand Down