Add considerations for client structure

[qiaozha]

Add some considerations for service client structure.

[johanste]

My SEK 0,02 - specific client structure guidance belongs in the SDK guidelines and should be reviewed by the SDK architects. There are several additional considerations that are purely client specific that goes into the decision (e.g. heavy package dependencies needed for subsets of functionality, lifetime of objects etc.) as well as different kinds of clients that sometimes are language specific (e.g. operation groups, clientlets etc.). This extends beyond clients and all the way into how many packages we produce for a given service.

My guidance is single package with a single client per service unless SDK team recommends more than one.

[qiaozha]

@johanste thanks for taking a look and sharing what is missing of the client structure consideration I will reconsider how to integrate those if possible. Also, could you point out where might be the appropriate place to put the guidance? Thank you.

I would still like to put more context in here, the target audience for this guidance is not only for SDK team, but also for service team who works on a new feature or even a new service.

I understand the main client structure is single package/single client pattern for ARM and maybe some data plane libraries, and one key point for single package/single client is that they have to version uniformly within single package. but the problem is we have several cases that indicate single package/single client per each service is no longer suitable/ or not being applied to them.

And people who work on new features or new service tend to have this kind of confusion as they need to be clear about how to organize their swagger/TypeSpec which essentially is a consideration for client structure. And I think it's better to a guidance for them at an earlier stage. if they need approval for different patterns, we can also specified it in the document?

• The first one is service like network, they now have more than 60 features team, and the communication effort of version uniformly has become extremely huge within their team.
• The second one is service like Resources RP, they have been splitting every feature into a single package, you may check out their spec configuration, basically each tag kind is a package. And they have already spited out more than ten packages.
• The third one is for some services, they have a set of operations that are tenant level's operation which is for roles with higher permission, they also have a set of operations that are non tenent level for normal roles. which is confusing to put them together.

And if there's no guideline, service team will just keep doing what they have been used to, network would have more and more feature teams and Resources RPs will have more and more packages, neither of those are a good user experience for our SDK customers.

/cc @JeffreyRichter for awareness.

[mikekistler]

I agree with Johan that guidance on client shape belongs in the SDK Guidelines. The guidelines already have guidance on this topic:

https://azure.github.io/azure-sdk/general_design.html#client-interface

but if more is needed then it should be added there and not in the REST API guidelines.

[DominikMe]

I like the idea of cross-linking to the SDK API guidelines; this could help with discoverability. "Looking for the SDK API guidelines? You find them here."

[qiaozha]

@mikekistler I have read the guideline you linked, it has covered multiclients organized in both parallel way and hierarchy way. I have been rethinking and I feel like what I want is a consideration guidance for service clients scalability. It's used for when a new set of services apis is added, how to choose among all the options from a long term perspective for the overall service including single packages vs. multiple packages, while client interface guideline is for single package?

My other concern is, the consideration guidance I am looking might not be able to be very accurate, is it appropriate to put it into the SDK API guideline?

The title of the file I am changing is called considerations for service design, and my case is a consideration for them during the design stage, except this consideration is related to SDK, which is not a thing that only the SDK team should care about, I think? If you think this file is only for considerations for APIs, then maybe I can create another file called considerations for SDKs?

My other thinking is that this consideration guidance can definitely not equal to SDK archboard review decision making. it's just a bref considerations introduction for service team to think about their SDK and what their options are.

Let me know if you have any more concerns. Thanks

[mikekistler]

The considerations for service design document in this repo currently only addresses the REST API design and I believe it should remain that way. If the SDK Architecture board agrees with the guidance you are proposing, they can find a way to include it in the SDK Guidelines, maybe even as a new "Considerations" document as we have here.

[qiaozha]

I have been thinking about this, and feel like maybe the rest api specs repo is the place where this kind of client structure considerations should go? similar like uniform versioning

Let me know if that makes sense to you @mikekistler @johanste ?

if yes, I am going to close this one and file a pr there and request you or other architects review when it's ready?

[mikekistler]

We do have some docs in the azure-rest-api-specs repo so maybe there's a place there for this content. I'd certainly favor that over including in the REST API guidelines. But I still think the SDK guidelines are probably the best location.