Document the use of raw URLs with request builders

baywet commented 11 months ago

In some cases the fluent API of kiota clients can be limiting (next links, delta links, expansion limitations on non canonical paths...)

Request builders can be passed a raw URL so the user can still call GetAsync and maintain type checks, serialization, etc...

A good example of that are file APIs for ODSP in the context of Microsoft Graph.

var myDrive = await _graphClient
┬á┬á┬á .Me
┬á┬á┬á .Drive
┬á┬á┬á .GetAsync();

┬á

var appFolder = await _graphClient
┬á┬á┬á .Drives[myDrive.Id]
┬á┬á┬á .Special["approot"]
┬á┬á┬á .GetAsync();

┬á

var fileStream = await _graphClient
┬á┬á┬á .Drives[myDrive.Id]
┬á┬á┬á .Items[appFolder.Id]
┬á┬á┬á .Children["myFile.json"]
┬á┬á┬á .Content
┬á┬á┬á .GetAsync();

Can be simplified to something like

var rawUrl = "the raw URL";
var fileStream = await new ContentRequestBuilder(requestAdapter, rawUrl).GetAsync();

This topic should also be referenced from MS Graph docs.

Originally created by @baywet at https://github.com/microsoftdocs/openapi-docs-pr/issues/26

sebastienlevert commented 10 months ago

I assume this is getting a lot easier with the WithUrl methods, right?

baywet commented 10 months ago

Right, now it'd be

var rawUrl = "the raw URL";
var fileStream = await _graphClient
       .Drives["foo"]
       .Items["bar"]
       .Children["zog"]
       .Content
       .WithUrl(rawUrl)
       .GetAsync()

MicrosoftDocs / openapi-docs

Document the use of raw URLs with request builders #10