v4.0.0-RestPreview.1 Initial Feedback

[sebastienlevert]

Here is a list of current feedback around the use of the 4.0.0-RestPreview.1. We will use this issue as a living "document" for now and might create specific issues for bigger items.

• [ ] Kiota should generate the models and Operations

Currently Kiota is not in use to generate the structure of the Operations and the models. This should be the case and Kiota should entirely support this scenario.

• [ ] Merge headers and oDataQueryOptions

• headers and oDataQueryOptions should be combines to avoid situations like these where we need to provide an empty headers object. Having an object accepting an header object and the options will feel more natural and will allow for optional parameters

From this

const users = await graphTypedRestClient.api("/users").get({}, { $filter: "userType eq 'guest'"});

To this

const users = await graphTypedRestClient.api("/users").get({ options: { $filter: "userType eq 'guest'"} });

• [ ] The client should return a REST Client vs. having to explicitely ask for one.

Instead of requesting to create a REST Client with the generated Graph client, we should get it directly with Client.Init.

let graphTypedRestClient = Client.init({
	authProvider: new SimpleAuthenticationProvider(async () => { return process.env.ACCESS_TOKEN! } ),
});

• [ ] DateTime should be respected

export interface MicrosoftGraphUser extends MicrosoftGraphDirectoryObject {
    //...
    createdDateTime?: string,
}

Should become similar to this :

export interface MicrosoftGraphUser extends MicrosoftGraphDirectoryObject {
    //...
    createdDateTime?: Date,
}

We should work with serializers and deserializers to infer the types.

• [ ] QueryOptions should use OData terms without the $

We should go from

const users = await graphTypedRestClient.api("/users").get({
	ConsistencyLevel: "Eventual"
}, {
	$count: true,
	$filter: "Department eq 'Finance'",
	$orderby: "displayName",
	$select: "id,displayName,department"
});

to

const users = await graphTypedRestClient.api("/users").get({
	ConsistencyLevel: "Eventual"
}, {
	count: true,
	filter: "Department eq 'Finance'",
	orderby: "displayName",
	select: "id,displayName,department"
});

• [ ] When using search in the QueryOptions, we shouldn't need to wrap the queries in quotes.

When calling the API, if not wrapped in quotes, we are receiving an error : Search doesn't work Syntax error: character ':' is not valid at position 11 in 'displayName:room'. when using the following query:

const users = await graphTypedRestClient.api("/users").get({
	ConsistencyLevel: "Eventual"
}, {
	$count: true,
	$filter: "endsWith(mail, 'microsoft.com')",
	$orderby: "displayName",
	$select: "id,displayName,email",
	$search: 'displayName:room'
	// It works that way
	$search: '"displayName:room"'
});

The SDK Should automatically add quotes to the search queries without the user to require to put them in the search query.

• [ ] Microsoft Graph Types should contain both Models and Operations

As a developer, I want to be able to leverage both tools in a single package. Especially because Operations and Models are tightly couples and specific to a version of Graph, it would make sense to deliver 2 packages :

• @microsoft/microsoft-graph-types
• @microsoft/microsoft-graph-types-beta

• [ ] A developer should be able to get a client for each version of Graph

Currently, we are tight to v1.0. We should offer an helper method in both Microsoft Graph Types to instantiate a Graph client that would deliver the specific endpoints for /beta or /v1.0.

Aliasing would be used to differentiate between clients and models (when they are different).

import { Client } from "@microsoft/microsoft-graph-types";
import { Client as BetaClient } from "@microsoft/microsoft-graph-types-beta";

let client = Client.init({ ... });
let client = BetaClient.init({ ... });

• [ ] @odata.count should be part of the collections when available

Currently, no response collections have the @odata.count property. When requesting { count: true } we should be able to use this property to drive pagination, etc.

• [ ] We can use .api() without an URL template and the experience breaks.

I'm using /sites as an example as it's not loaded imported in my file and now I can se all sorts of weird things on the .api() method that I can't find.

This experience should fail and intellisense should provide help by suggesting importing the sitesAndLists module.

• [ ] Debugging the core client allow getting a callback for every request.

Currently, debugging is possible using the following code :

graphTypedRestClient = getGraphRestSDKClient(Client.init({    
	authProvider: new SimpleAuthenticationProvider(async () => { return process.env.ACCESS_TOKEN! } );
	debugLogging: true
}));

This helps but uses a console.log instead of something we can intercept. It would be better to provide a more elaborate way to get the URL. This would allow to test the generated URLs in a static way (vs. calling Graph).

[nikithauc]

Along with the feedback by @sebastienlevert, feedback in #979 to be taken into consideration.