Add graph pattern for common query functions

[corranrogue9]

Adding the guidance pattern according to this ADR. The pattern is to use OData functions as "aliases" for the more complicated or common OData query options for robust APIs that support a wide range of query options.

[mikepizzo]

Query option aliasing

I'm not sure that the name "Query option aliasing" lands for me, although I understand your intent.

Maybe something like "Exposing functions for common queries"?

[corranrogue9]

I didn't remove all references to the word alias, but I made some changes, let me know if you think I need to go deeper

[mikepizzo]

🕐

[mikepizzo]

Although you do allude to it in the Issues and Considerations, I would mention here that the solution is applied when the request being aliased is more complex/less intuitive to construct.

Suggested change

	The solution to this problem is to provide support for the query options and to additionally define OData functions that act as aliases for a specific set of query options.
	The solution to this problem is to provide support for the query options and to additionally define OData functions that act as aliases for a specific set of query options that represent a common request that may be more complex/less intuitive to construct.

[mikepizzo]

Wording feels a bit awkward.

Suggested change

	*Exposing functions for common queries is providing functions with friendly names as an additional mechanism for clients to make certain kinds of requests that involve the use of OData query options.*
	*Exposing functions for common queries provides friendly names as an additional mechanism for clients to make certain kinds of requests that involve the use of OData query options.*

[mikepizzo]

Suggested change

	However, the OData query options that need to be used by clients can become complicated and confusing.
	However, the OData query options used by clients to express certain more complex queries can become complicated and confusing.

[mikepizzo]

in this context, I would think of it not as experience with OData (most graph folks probably don't think of themselves as OData) but as experience with OData query options (subtle distinction, I know)

Suggested change

Because of this, API producers have a tendency to avoid supporting query options that require client developers to have OData experience; avoiding these query options results in APIs that are not fully featured and are not externally extensible, limiting what clients can actually accomplish via the APIs.

Because of this, API producers have a tendency to avoid supporting common query options to express such requests in favor of special purpose functions. However, avoiding these common query options results in APIs that are not fully featured and are not externally extensible, limiting what clients can actually accomplish via the APIs. This can also lead to a proliferation of special purpose functions to express each unique request.

[mikepizzo]

This makes it sound like it's fine to ship a special purpose function because, if in the future they decide they want something more flexible, they could add it. I'm afraid that would lead to workloads using this guidance to say "I have a bunch of functions today, and might add more in the future, cause the guidance says that I can always add $filter later."

I would think that we would want to encourage workloads to move to the more general solution and not rely on exposing everything through custom functions.

Suggested change

	It is likewise fine to ship a handful of functions and then later ship an API that is a collection of data with a more fully-featured set of filters.
	While it is possible to start with one or two custom functions, you should have a plan to support a more fully-featured set of query options as the utility of your API will be significantly limited in the interim.