Change Request: Protocol Layer Description for General Guidelines

[adrianhall]

The Basics

• Which design guideline is affected?

New Guideline in the "API Surface" Layer

• Which target languages are affected?

All hierarchical languages.

• Describe the change:

~ Must
Provide access to the underlying auto-generated REST library that provides access to 100% 
of the service functionality.  In hierarchical objects, this access should be through a member
 called `Protocol`.
~

~ Must
Only include methods within the service client required to support use cases that the majority 
of consumers will handle.  Defer all other use cases to either a supporting library or the Protocol 
object.
~

Reasoning

In many client libraries, the actual surface that a typical application uses is minuscule and much less than the 100% functionality of the service. Our aim should be to reduce the API surface exposed to the majority of consumers while still maintaining high fidelity with the service.

To do this, we split the client library into three portions:

• A protocol layer whose only job is to interact with the REST interface of the service. This should be auto-generated from the Swagger.
• A "use case specific" convenience layer - a set of methods that provide the appropriate methods to implement common use cases.
• Other methods within the convenience layer can be added on an as needed (additive) basis.

This means we will be making value judgments on the admissibility of the a use case to the convenience layer. How likely is the use case to the common consumer? Is it common in a back-end web service, a single-page application, or a mobile or desktop app? What percentage of consumers are likely to need the functionality?

Common use cases should be easy. All other use cases should be possible.

Examples:

• KeyVault - getting the latest version of a secret from the secret store is a common use case. Listing all the versions of a secret, or updating a secret is not a common use case. The former should have a nice convenience layer - the latter probably not.
• Storage - uploading and downloading a blob is a common use case. Updating specific blocks in a block blob probably is not a common use case.
• Cosmos - the typed search capabilities are probably core. The streaming capabilities are probably not.

[adrianhall]

Copying @KrzysztofCwalina @JeffreyRichter @johanste @GorNishanov @bterlson @JonathanGiles

[adrianhall]

Proposal was rejected by the board.