From 6e1854b67982b275a2c22cb54acfff745ab59ae6 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 18 Dec 2023 09:49:57 -0800 Subject: [PATCH 01/12] Create query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 30 +++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 graph/patterns/query-option-aliasing.md diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md new file mode 100644 index 00000000..c4bfec92 --- /dev/null +++ b/graph/patterns/query-option-aliasing.md @@ -0,0 +1,30 @@ +# Query option aliasing + +Microsoft Graph API Design Pattern + +*Provide a short description of the pattern.* + + +## Problem + +*Describe the business context relevant for the pattern.* + +*Provide a short description of the problem.* + +## Solution + +*Describe how to implement the solution to solve the problem.* + +*Describe related patterns.* + +## When to use this pattern + +*Describe when and why the solution is applicable and when it might not be.* + +## Issues and considerations + +*Describe tradeoffs of the solution.* + +## Example + +*Provide a short example from real life.* From 422345ac5bdd7128b4179f9121d5929d30f6a0a1 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 18 Dec 2023 09:55:05 -0800 Subject: [PATCH 02/12] Update query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md index c4bfec92..d5b4d95c 100644 --- a/graph/patterns/query-option-aliasing.md +++ b/graph/patterns/query-option-aliasing.md @@ -2,14 +2,15 @@ Microsoft Graph API Design Pattern -*Provide a short description of the pattern.* +*Query option aliasing 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.* ## Problem -*Describe the business context relevant for the pattern.* - -*Provide a short description of the problem.* +Some APIs are very data-focused. +These APIs are generally capable of providing robust `$fitler`ing and `$expand`ing functionality. +However, the OData query options that need to be used by clients can become complicated and confusing. +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. ## Solution From 50128e64cfeef523f7a8374c1aa92fff6d9f9cc5 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 18 Dec 2023 10:01:59 -0800 Subject: [PATCH 03/12] Update query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md index d5b4d95c..5cdf96c8 100644 --- a/graph/patterns/query-option-aliasing.md +++ b/graph/patterns/query-option-aliasing.md @@ -14,17 +14,24 @@ Because of this, API producers have a tendency to avoid supporting query options ## Solution -*Describe how to implement the solution to solve the problem.* +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. +Doing this gives client developers a low barrier-of-entry to using the API (familiarizing themselves with the shape of the data), and it also gives those developers extensiblity in the future to grow beyond the basic cases to write clients that are specific to their own business needs. +The functions can further provide discoverability by using names for concepts that customers are familiar with, letting them know that those concepts are supported. -*Describe related patterns.* +//// TODO example ## When to use this pattern -*Describe when and why the solution is applicable and when it might not be.* +This pattern can be employed in almost any circumstance. +It is also able to be used once an API as shipped and in any order. +It is ok to ship a data-focused API with robust `$filter`ing support, and *later* ship functions that alias certain specific filters. +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. ## Issues and considerations -*Describe tradeoffs of the solution.* +The tradeoff with this pattern is ensuring that the functions don't become so numerous that they remove the aliasing benefit. +It is important to remember that the functions exist to lower dicsoverability, decrease onboarding costs, and prevent client mistakes writing complicated OData queries. +If an alias is being considered that does not directly address one of these issues, it likely shouldn't be aliased. ## Example From 66c501c3528b0e5e4886e77fe7c79d3e60a7cffa Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 18 Dec 2023 10:02:10 -0800 Subject: [PATCH 04/12] Update query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md index 5cdf96c8..fad03d3c 100644 --- a/graph/patterns/query-option-aliasing.md +++ b/graph/patterns/query-option-aliasing.md @@ -4,7 +4,6 @@ Microsoft Graph API Design Pattern *Query option aliasing 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.* - ## Problem Some APIs are very data-focused. From 0454ea44bbb13794ce9e937c7321d4a1423c238f Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 18 Dec 2023 10:16:36 -0800 Subject: [PATCH 05/12] Update query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 49 ++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md index fad03d3c..c71a249e 100644 --- a/graph/patterns/query-option-aliasing.md +++ b/graph/patterns/query-option-aliasing.md @@ -17,7 +17,54 @@ The solution to this problem is to provide support for the query options and to Doing this gives client developers a low barrier-of-entry to using the API (familiarizing themselves with the shape of the data), and it also gives those developers extensiblity in the future to grow beyond the basic cases to write clients that are specific to their own business needs. The functions can further provide discoverability by using names for concepts that customers are familiar with, letting them know that those concepts are supported. -//// TODO example +Suppose that you have a collection of attempted sign-ins for an organization. You might model this as: + +```xml + + + + + + + + + + + + + + + + + + +``` + +Clients could then request all of the successful, multifactor sign-in attempts by calling: + +```http +GET /signInAttempts?$filter=isSuccessful eq true and otherFactorsUsed/any(factor: true) + +HTTP/1.1 200 OK +{ + "value": [ + { + "id": "{id1}", + "firstFactorUsed": { + // other properties here + }, + "otherFactorsUsed": [ + { + // other properties here + }, + ... + ], + "isSuccessful": true + }, + ... + ] +} +``` ## When to use this pattern From c3f19b5f01bc66f7333c67cf153cc6c64bf6fdd0 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 18 Dec 2023 10:19:50 -0800 Subject: [PATCH 06/12] Update query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 39 ++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md index c71a249e..b093e6c5 100644 --- a/graph/patterns/query-option-aliasing.md +++ b/graph/patterns/query-option-aliasing.md @@ -43,7 +43,7 @@ Suppose that you have a collection of attempted sign-ins for an organization. Yo Clients could then request all of the successful, multifactor sign-in attempts by calling: ```http -GET /signInAttempts?$filter=isSuccessful eq true and otherFactorsUsed/any(factor: true) +GET /signInAttempts?$filter=isSuccessful eq true and otherFactorsUsed/$count ne 0 HTTP/1.1 200 OK { @@ -66,6 +66,43 @@ HTTP/1.1 200 OK } ``` +An API producer could alias this common filtering use case by adding a function to the CSDL: + +```xml + + + + +``` + +Clients would then be able to call: + +```http +GET /signInAttempts/successfulMultifactorSignIns + +HTTP/1.1 200 OK +{ + "value": [ + { + "id": "{id1}", + "firstFactorUsed": { + // other properties here + }, + "otherFactorsUsed": [ + { + // other properties here + }, + ... + ], + "isSuccessful": true + }, + ... + ] +} +``` + +to retreive the same data. + ## When to use this pattern This pattern can be employed in almost any circumstance. From 4d6d0781125222cd9a5a6075c7e0cb836c40ac55 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Mon, 18 Dec 2023 10:20:48 -0800 Subject: [PATCH 07/12] Update query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 34 ++++++++++++------------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md index b093e6c5..dc6beac6 100644 --- a/graph/patterns/query-option-aliasing.md +++ b/graph/patterns/query-option-aliasing.md @@ -17,7 +17,22 @@ The solution to this problem is to provide support for the query options and to Doing this gives client developers a low barrier-of-entry to using the API (familiarizing themselves with the shape of the data), and it also gives those developers extensiblity in the future to grow beyond the basic cases to write clients that are specific to their own business needs. The functions can further provide discoverability by using names for concepts that customers are familiar with, letting them know that those concepts are supported. -Suppose that you have a collection of attempted sign-ins for an organization. You might model this as: +## When to use this pattern + +This pattern can be employed in almost any circumstance. +It is also able to be used once an API as shipped and in any order. +It is ok to ship a data-focused API with robust `$filter`ing support, and *later* ship functions that alias certain specific filters. +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. + +## Issues and considerations + +The tradeoff with this pattern is ensuring that the functions don't become so numerous that they remove the aliasing benefit. +It is important to remember that the functions exist to lower dicsoverability, decrease onboarding costs, and prevent client mistakes writing complicated OData queries. +If an alias is being considered that does not directly address one of these issues, it likely shouldn't be aliased. + +## Example + +Suppose that there is a collection of attempted sign-ins for an organization. The model might look like this: ```xml @@ -102,20 +117,3 @@ HTTP/1.1 200 OK ``` to retreive the same data. - -## When to use this pattern - -This pattern can be employed in almost any circumstance. -It is also able to be used once an API as shipped and in any order. -It is ok to ship a data-focused API with robust `$filter`ing support, and *later* ship functions that alias certain specific filters. -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. - -## Issues and considerations - -The tradeoff with this pattern is ensuring that the functions don't become so numerous that they remove the aliasing benefit. -It is important to remember that the functions exist to lower dicsoverability, decrease onboarding costs, and prevent client mistakes writing complicated OData queries. -If an alias is being considered that does not directly address one of these issues, it likely shouldn't be aliased. - -## Example - -*Provide a short example from real life.* From 3153d37964189712438bcc49cc8d35cc957c9d55 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Wed, 20 Dec 2023 07:32:58 -0800 Subject: [PATCH 08/12] Update query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md index dc6beac6..e0f45903 100644 --- a/graph/patterns/query-option-aliasing.md +++ b/graph/patterns/query-option-aliasing.md @@ -1,4 +1,4 @@ -# Query option aliasing +# Exposing functions for common queries Microsoft Graph API Design Pattern From 8d4edc82eec4e8eebcfc6049353445876c4e1b3a Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Wed, 20 Dec 2023 07:34:40 -0800 Subject: [PATCH 09/12] Update query-option-aliasing.md --- graph/patterns/query-option-aliasing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/query-option-aliasing.md index e0f45903..72bbf4f2 100644 --- a/graph/patterns/query-option-aliasing.md +++ b/graph/patterns/query-option-aliasing.md @@ -2,7 +2,7 @@ Microsoft Graph API Design Pattern -*Query option aliasing 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 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.* ## Problem @@ -21,14 +21,14 @@ The functions can further provide discoverability by using names for concepts th This pattern can be employed in almost any circumstance. It is also able to be used once an API as shipped and in any order. -It is ok to ship a data-focused API with robust `$filter`ing support, and *later* ship functions that alias certain specific filters. +It is ok to ship a data-focused API with robust `$filter`ing support, and *later* ship functions that act in the same way as certain specific filters. 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. ## Issues and considerations The tradeoff with this pattern is ensuring that the functions don't become so numerous that they remove the aliasing benefit. It is important to remember that the functions exist to lower dicsoverability, decrease onboarding costs, and prevent client mistakes writing complicated OData queries. -If an alias is being considered that does not directly address one of these issues, it likely shouldn't be aliased. +If a function is being considered that does not directly address one of these issues, it likely shouldn't be introduced. ## Example From 678d9185ce124657f820f757172ec9805f5f79d0 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Wed, 20 Dec 2023 07:35:19 -0800 Subject: [PATCH 10/12] Rename query-option-aliasing.md to common-query-functions.md --- .../{query-option-aliasing.md => common-query-functions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename graph/patterns/{query-option-aliasing.md => common-query-functions.md} (100%) diff --git a/graph/patterns/query-option-aliasing.md b/graph/patterns/common-query-functions.md similarity index 100% rename from graph/patterns/query-option-aliasing.md rename to graph/patterns/common-query-functions.md From 23a39af6e8230ba5f531bc79b4f579b53fb95ac4 Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Wed, 20 Dec 2023 07:37:12 -0800 Subject: [PATCH 11/12] Update common-query-functions.md --- graph/patterns/common-query-functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/graph/patterns/common-query-functions.md b/graph/patterns/common-query-functions.md index 72bbf4f2..75cfb5bf 100644 --- a/graph/patterns/common-query-functions.md +++ b/graph/patterns/common-query-functions.md @@ -27,7 +27,7 @@ It is likewise fine to ship a handful of functions and then later ship an API th ## Issues and considerations The tradeoff with this pattern is ensuring that the functions don't become so numerous that they remove the aliasing benefit. -It is important to remember that the functions exist to lower dicsoverability, decrease onboarding costs, and prevent client mistakes writing complicated OData queries. +It is important to remember that the functions exist to lower discoverability, decrease onboarding costs, and prevent client mistakes writing complicated OData queries. If a function is being considered that does not directly address one of these issues, it likely shouldn't be introduced. ## Example From 131237d15ed2e5cab47f201096798913bac5003f Mon Sep 17 00:00:00 2001 From: Garrett DeBruin <16618938+corranrogue9@users.noreply.github.com> Date: Wed, 20 Dec 2023 07:37:34 -0800 Subject: [PATCH 12/12] Update common-query-functions.md --- graph/patterns/common-query-functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/graph/patterns/common-query-functions.md b/graph/patterns/common-query-functions.md index 75cfb5bf..07d5ce54 100644 --- a/graph/patterns/common-query-functions.md +++ b/graph/patterns/common-query-functions.md @@ -27,7 +27,7 @@ It is likewise fine to ship a handful of functions and then later ship an API th ## Issues and considerations The tradeoff with this pattern is ensuring that the functions don't become so numerous that they remove the aliasing benefit. -It is important to remember that the functions exist to lower discoverability, decrease onboarding costs, and prevent client mistakes writing complicated OData queries. +It is important to remember that the functions exist to increase discoverability, decrease onboarding costs, and prevent client mistakes writing complicated OData queries. If a function is being considered that does not directly address one of these issues, it likely shouldn't be introduced. ## Example