graph-interface

Simple Microsoft Graph API client.

Important: This version have breaking changes and is not compatible with the previous version.

Similar projects

• Microsoft Graph JavaScript Client Library - The official JS/TS client;

• GraphInterface - The .NET version of this package.

Why?

As you may noticed, there is already an official package to deal with the Graph API requests, and it's very well done. It have all the abstractions and provides a nice API to work with.

However, some things are not available in the official package, like the ability to make massive requests and a simplified way to authenticate with the API.

In general, I would say that you probably should use the official package, but if you really need to make massive requests, you can use this package.

Installation

You can get this package on NPM

Usage

Importing

CommonJS:

const GraphInterface = require('graph-interface');

ES Modules:

import GraphInterface from 'graph-interface';

Initialization

The imported GraphInterface function is used to create a new instance of the client. It requires the credentials and accepts additional options to change the behavior of the client:

const graph = GraphInterface(credentials, options);

The credentials object requires the following properties:

interface Credentials {
    tenantId: string;
    clientId: string;
    clientSecret: string;
}

• tenantId - The ID of the Tenant where the application is registered;
• clientId - The ID of the application itself registered in the Tenant;
• clientSecret - The secret of the application, generated by the developer in the application settings.

As an optional parameter, the options object have the following properties:

Note: The options properties are all optional, as the following interface will be wrapped in a Partial<T> type.

interface GraphOptions {
    version: string;
    logger?: Logger;
    authenticationProvider?: AuthenticationProvider;
    cacheService?: CacheService;
    cacheAccessTokenByDefault: boolean;
}

• version - The version of the Graph API to use. Default v1.0;

• logger - An Logger function to log the internal processing of requests in the package. Default undefined;

• authenticationProvider - An AuthenticationProvider function, that will be called to get the access token. If not provided, the client will use the default getAccessToken behavior;

• cacheService - An CacheService object to use to cache access tokens and responses if needed. Default MemoryCache();

• cacheAccessTokenByDefault - If true, the client will cache the access token by default. If cacheService is set to null, this option will be ignored. Default true.

Option types and interfaces:

Logger type:

type Logger = (message: string) => void | Promise<void>;

AuthenticationProvider interfaces:

type AuthenticationProvider = (credentials: Credentials) => Promise<AccessTokenResponse> | AccessTokenResponse;

interface AccessTokenResponse {
    accessToken: string;
    expiresIn: number;
    tokenType: string;
    refreshToken?: string;
    extExpiresIn: number;
    expiresOn?: number;
    notBefore?: Date;
    resource?: string;
}

CacheService interfaces:

interface CacheService {
    get: CacheGet;
    set: CacheSet;
    expire: CacheExpire;
    has: CacheHas;
}

type CacheGet = <T>(key: string) => Promise<T>;
type CacheSet = <T>(key: string, value: T, expiration?: number) => Promise<void>;
type CacheExpire = (key: string) => Promise<void>;
type CacheHas = (key: string) => Promise<boolean>;

Methods

• getAccessToken - Get the access token to use the Graph API, used most internally, but if need for a custom request, you can get it from here;

• unit - Makes requests that return a single entity;

• list - Makes requests that return a list of entities, paginated using the @odata.nextLink property;

• massive - Makes batch requests based on a template URL and a list of values to interpolate, generating a lot of similar requests.