-
Notifications
You must be signed in to change notification settings - Fork 2.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add graph pattern for common query functions #512
Open
corranrogue9
wants to merge
12
commits into
vNext
Choose a base branch
from
corranrogue9/queryoptionaliasing
base: vNext
Could not load branches
Branch not found: {{ refName }}
Could not load tags
Nothing to show
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 7 commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
6e1854b
Create query-option-aliasing.md
corranrogue9 422345a
Update query-option-aliasing.md
corranrogue9 50128e6
Update query-option-aliasing.md
corranrogue9 66c501c
Update query-option-aliasing.md
corranrogue9 0454ea4
Update query-option-aliasing.md
corranrogue9 c3f19b5
Update query-option-aliasing.md
corranrogue9 4d6d078
Update query-option-aliasing.md
corranrogue9 3153d37
Update query-option-aliasing.md
corranrogue9 8d4edc8
Update query-option-aliasing.md
corranrogue9 678d918
Rename query-option-aliasing.md to common-query-functions.md
corranrogue9 23a39af
Update common-query-functions.md
corranrogue9 131237d
Update common-query-functions.md
corranrogue9 File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,119 @@ | ||
# Query option aliasing | ||
|
||
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. | ||
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 | ||
|
||
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. | ||
|
||
## 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. | ||
corranrogue9 marked this conversation as resolved.
Show resolved
Hide resolved
corranrogue9 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 | ||
<EntityContainer Name="container"> | ||
<EntitySet Name="signInAttempts" EntityType="self.signInAttempt" /> | ||
</EntityContainer> | ||
|
||
<EntityType Name="signInAttempt"> | ||
<Key> | ||
<PropertyRef Name="id" /> | ||
</Key> | ||
<Property Name="id" Type="Edm.String" Nullable="false" /> | ||
|
||
<Property Name="firstFactorUsed" Type="self.authenticationFactor" Nullable="false" /> | ||
<Property Name="otherFactorsUsed" Type="Collection(self.authenticationFactor)" Nullable="false" /> | ||
<Property Name="isSuccessful" Type="Edm.Boolean" Nullable="false" /> | ||
</EntityType> | ||
|
||
<ComplexType Name="authenticationFactor"> | ||
<!--other properties here--> | ||
</ComplexType> | ||
``` | ||
|
||
Clients could then request all of the successful, multifactor sign-in attempts by calling: | ||
|
||
```http | ||
GET /signInAttempts?$filter=isSuccessful eq true and otherFactorsUsed/$count ne 0 | ||
|
||
HTTP/1.1 200 OK | ||
{ | ||
"value": [ | ||
{ | ||
"id": "{id1}", | ||
"firstFactorUsed": { | ||
// other properties here | ||
}, | ||
"otherFactorsUsed": [ | ||
{ | ||
// other properties here | ||
}, | ||
... | ||
], | ||
"isSuccessful": true | ||
}, | ||
... | ||
] | ||
} | ||
``` | ||
|
||
An API producer could alias this common filtering use case by adding a function to the CSDL: | ||
|
||
```xml | ||
<Function Name="successfulMultifactorSignIns" IsBound="true"> | ||
<Parameter Name="bindingParameter" Type="Collection(self.signInAttempt)" Nullable="false" /> | ||
<ReturnType Type="self.signInAttempt" /> | ||
</Function> | ||
``` | ||
|
||
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. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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