Feedback of Version 1 and Version 2

[AlexanderAdelAU]

With reference to the version description https://github.com/microsoftgraph/msgraph-sdk-php/blob/dev/UPGRADING.md and request for comments regarding the new syntax.

I don't know what the consensus was but my 2 cents would be to support both (although looking at the source code it looks like the v1 syntax is no longer supported) . My opinion we should remain as close to the graph endpoints as possible, abstracting away from the ms-graph endpoints makes the interfacing very subjective and far from obvious - I hope this is not too late. The ability to modify attributes to adapt to different scenarios has to be easier with the V1 as well - I would have thought.

// v1.x $response = $graphClient->createRequest('GET', '/users/userId/messages') ->setReturnType(Model\User::class) ->execute(); // v2.0 $response = $graphServiceClient->users()->byUserId('userId')->messages()->get()->wait();

[Ndiritu]

Thanks for your feedback @AlexanderAdelAU.

The new design was motivated by reducing the back and forth between checking the API reference docs for the correct endpoint and the expected model type and allow a fluent auto-completion experience to guide you through the SDK once you type $graphServiceClient->....

Would you mind sharing some scenarios where the v2 fluent experience makes things more difficult? Also, would you mind expanding more on "The ability to modify attributes to adapt to different scenarios has to be easier"?

[AlexanderAdelAU]

Thanks Ndiritu, these things are subjective but my main point is that in my opinion and what I perceive after having spend a great deal of time attempting to surmount some of the issues with MSGraph when accessing shared folders etc. I would have never figured it all out (and identified the bugs/design issues) without access to the MS Graph Endpoints Tools. And I suppose my point is that, once sorted out one would then need to port them to another syntax (i.e. V2), and I think that is my point in a limited sense.

[flohw]

Hi,

As I opened some issue (one of them is closed) and if I understood correctly what AlexanderAdelAU wirtes, the hardest part for us with the v2 is to know when and what to provide in the different RequestConfiguration parameters. Not only these parameters but they are part of the issue.

Additionally the model objects do not always represent the graph response where we previously had a desirialized json which was exactly what the graph response is and easier to refer, read and understand from the documentation and graph explorer.

To point out one of my experience is my issue #1460 or the question I asked myself: "where should I create the @microsoft.graph.conflictBehavior option? In additional data of the drive item or the request configuration ?". Same applies with the Prefer header for the contact api. Maybe both of them are due to my lack of large knowledge of the graph api but I also found the v1 easier to use and at the same time the v2 is clearer to read and discover. Maybe it's only a question of a more explicit documentation of the SDK? As mentioned in my #1461 I copied the code provided by the documentation, it doesn't work and I can't figure out what's wrong because of a high level of abstraction (streams are not easy to understand/master) and error response given by the api miss some information too. ("Invalid request" is not really helpful :wink: )

Thank you for your time.

Note: I am not an intense user of the api but what I use it for is very important for the project. (read: I won't be able to help a lot on tests or make recommendation due to my limited knowledge of the graph api)

[dearsina]

I am an active user of the PHP SDK v1 for browsing folders and managing file uploads to OneDrive and SharePoint. I upgraded to v2 today, thinking it will fix some of the edge case issues we were having with v1, but in hindsight, this was a huge mistake.

In v1, most calls require building a simple URL (that matches the Graph Explorer) and using the createRequest method. In v2, you need a Russian-doll like approach to building objects inside objects inside objects, then linking method to method to method to achieve the same goal. Few of the methods are very intuitive, even fewer are documented beyond that simple URL, and some are not documented at all.

Here are a couple of examples.

Uploading a file In v1, I wrote the following simple request.

$response = $this->graph->setApiVersion("v1.0")
	->createRequest("PUT", "/sites/{$key['site_id']}/drive/items/{$key['item_id']}:/{$file['name']}:/content")
	->addHeaders(["Content-Type" => $file['type'],])
	->upload($file['tmp_name']);

How do you upload a file in v2? Well, let's have a look at the documentation shall we. Oh, it just lists the URLs from v1, no PHP SDK examples. Not very helpful. I had a look at the documentation for uploading "large" files, and not only is the example code complicated, it's incomplete.

Updating a token Here's another example. In v1, all I had to do to update the token was to call

$this->graph->setAccessToken($new_token);

I have no idea what the equivalent in v2 is, and the documentation is so convoluted that I'm struggling to get my head around it.

I hear what you're saying about v2 being an attempt to reduce dependency on the documentation, which is a laudable goal, however, I fear the result is quite the opposite, not only is it impossible to navigate without the documentation, in most cases, the documentation doesn't even exist.

I think I'll go back to v1, and just deal with the edge cases.

[uncaught]

Honestly, I'm considering dropping this SDK altogether again. An SDK should make development easier, but this is just not worth the time.

I've spent hours these days trying to get an upload to work into the user's OneDrive Apps folder, which should be a simple PUT /drive/special/approot:/{fileName}:/content according to the documented API.

But I couldn't get it to work at all with the SDK. None of the nodes are there. It should be something like $graph->me()->drive()->special()->byDriveItemId('approot')->content()->put()->wait();, but that doesn't exist. And I cannot find work-arounds for missing routes, either.

In the end, I simply used a browser directly (we already use Buzz\Browser), so this was just a few lines:

$response = $browser->put("https://graph.microsoft.com/v1.0/me/drive/special/approot:/$filenameOneDrive:/content", [
  'Authorization' => "Bearer $accessToken",
  'Content-Type' => $mimeType,
], $fileContent);

Then our vendor/microsoft-folder is more than 50% of all our vendor code with its 200+ MiB. There is so much boilerplate code in there that could be reduced. And if I skim the updates of the last months, it all seems to be comments only, no code. My IDE gets a heart attack re-indexing every time I update this dependency.

So if we don't use this SDK for maintaining the access tokens, are not getting a complete interface for the API, are not even protected from quirks the API might yield (e.g. not noticing pagination is a thing), have no documentation and instead need to guess interface nodes from the official API documentation, then what benefit do I get from using this?

[flohw]

Hi,

As mentioned earlier (the V2 sdk is poorly designed and look like a code generation from another language) and my #1461 not resolved for a more than a year (even real open source maintainers have a better reactivity) I created my own classes for my usage. It's not perfect but it works as expected, understandable, readable and usable (if the api works)

It's built with symfony/http-client. I can share on a gist if asked.

[dearsina]

It's built with symfony/http-client. I can share on a gist if asked.

Please share. Who knows, maybe we can create a useful SDK so that fellow PHP devs don't suffer the wrath V2.

[flohw]

Here is my example : https://github.com/flohw/microsoft-basic-sdk I hope everything will be clear and I did not forget something. I don't think it's usable "as is" but the lines are here.

The two distinct services to use are App\Microsoft\Contact\Contact to create/update/delete contacts. And App\Microsoft\Onedrive\Onedrive to manage a bit some drive items. I interact with the API as an app, not as a user (no OAuth) so you have configure it on your Azure portal.

I don't use the graph api a lot, I am not a MS expert nor GraphAPI expert and don't intend to be. I hope it will inspire someone to create something reliable.