Add considerations for client structure #549
Conversation
|
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. |
| ## Service Client Structure | ||
| The client structure of a service is not solely a decision for the SDK side; it is also closely related to the service's conceptual model, API complexity and size, and usage patterns. This decision should be made upfront to ensure the client structure accurately represents the service and provides the best user experience. As the service grows, the client structure should evolve accordingly. A well-considered client structure can also reduce communication efforts within the service's feature teams. | ||
|
|
||
| A client refers to a set of service APIs that share the same endpoint and can be uniformly versioned. A package can contain multiple clients, which can be organized in a parallel or hierarchical structure depending on the service's conceptual model. And a service can have multiple packages. Which leads to four kinds of different client structures: **Single Client in Single Package**, **Multiple Parallel Clients in Single Package**, **Multiple Hierarchy Clients in Single Package**, **Multiple Packages**. And for a given service, our considerations for choosing between different client structures are as following: |
There was a problem hiding this comment.
Anything other than single-package, single-client is an exception to the rule.
There was a problem hiding this comment.
Good starting point, but it is the wrong document to add the guidance to. Also, I would expect a much stronger preference for the single package/single client pattern since that is the default answer, and the different options need to have justification/get approval from the SDK team.
|
@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?
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. |
|
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. |
|
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." |
|
@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 |
|
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. |
Add some considerations for service client structure.