GraphClientsDesign.md

[nikithauc]

[nikithauc]

Not sure if it's outside of the scope of this change but having some explanation of the difference between service and core libs, why we need them both and if they're both relevant to developers working with our SDKs (and if so when) would help everyone who's not familiar with this architecture.

@waldekmastykarz #558 should contain some of the answers.

The service libraries are the fluent libraries which contain the generated code. For example, the msgraph-sdk-dotnet today. The service libraries wrap the core libraries (like msgraph-sdk-dotnet wraps the msgraph-sdk-dotnet-core).

The core library contain the logic to make the http calls, middlewares, authentication, tasks such as page iteration and logic.

The current Graph JS SDK library which contains the client.api() call. For users who opt out of the fluent style can use the core library alone.

[waldekmastykarz]

Thank you for the additional information @nikithauc. My understanding was the the service library also exposes core library functionality. If that's the case, couldn't we just ship the service library to avoid providing additional choices and guidance around when developers should use which library and instead just have one resource to point them to?

[baywet]

@waldekmastykarz we're on a model of service libraries depending on one core library to avoid duplication. Technically there are 5 clouds x 2 version = 10 different APIs with more or less "endpoints". https://docs.microsoft.com/en-us/graph/deployments People using any service library will get all the functionality offered in core as core will be a dependency. Don't hesitate to hesitate to review our sdk design principles to get a better sense of those decisions.

[sebastienlevert]

@waldekmastykarz question stays valid though. When to use core vs. when to use service library when you are looking at "only" the .api() approach to call the API.

This is how I think about it (in the world of JavaScript or even in larger discussions about SDKs).

• Core is for users that want to leverage the underlying capabilities (middlewares, authentication, tasks, etc.) and don't need the fluent API, nor want to update their packages with every new release of the service library (which would be weekly). Only advanced scenarios would require this.
• Service library is a library that composes Core and offers the fluent API. This is the library we want most of our users to use to help with endpoint discoverability but also to offer the best developer experience possible.

Documentation, guidance, and patterns will all be built with the service library as it will uncover all the value from Core and more.

[waldekmastykarz]

Core is for users that want to leverage the underlying capabilities (middlewares, authentication, tasks, etc.)

@sebastienlevert does that mean that you won't be able to use middleware with the service library?

nor want to update their packages with every new release of the service library

I think we need to be careful how we frame it because there's a risk people will read it as: if I don't update my library each week, my app will break, which isn't the case. You only need to update if you want to get access to the latest APIs introduced in Graph. On top, it's a good pattern to keep dependencies up-to-date to benefit from latest fixes and improvements and that's a general rule rather than something specific to Graph SDKs.

If we want developers to use the service library with fluent APIs, then we should lead with it, underline its benefits and ensure that all code samples that we offer, from docs to Graph Explorer, show its usage.

[sebastienlevert]

@waldekmastykarz the service library has all the features of the core. So you will absolutely be able to add, modify and play with the middlewares. So as you say, we should lead with the service library, have all samples built with it and we should almost not discuss about the core. The service library becomes the entry point for Graph (like it is for any other language, to be honest). The only difference here is that JavaScript never had a concept of service library so people were effectively using "core" in the past. We have to be careful with the messaging and be clear about the USP.

[waldekmastykarz]

Understood. I wonder if we should use the terms Service- and Core library publicly, or if we should just call it a Graph SDK where the default experience is the fluent API but you can fallback to raw REST calls if need be.

[sebastienlevert]

Agree with your last statement. It would be called the Graph SDK. Nothing specific to "Service". Same we do with other languages.