Additional metadata to drive more robust query behavior

[jansenbe]

Today we do make SharePoint REST and Microsoft Graph calls. For SharePoint REST the possible ODATA query options are consistent and things work fine, for Graph however there's a lot of inconsistency that today results in failing Graph queries. Adding additional attributes will further help to prevent bad queries and throw detailed exceptions instead. Below table defines possible extra metadata to collect:

Name	Type or Property attribute	Default value	Graph	REST
AppOnlySupport	Type	true	X	X
SupportsFilter	Property	false	X
SupportedFilters	Property		X
SupportsTop	Property	false	X
SupportsSkip	Property	false	X
SupportsOrderBy	Property	false	X
DelegatedCreateScope	Type	depends on type	X	X
DelegatedReadScope	Type	depends on type	X	X
DelegatedUpdateScope	Type	depends on type	X	X
DelegatedDeleteScope	Type	depends on type	X	X
AppOnlyCreateScope	Type	depends on type	X	X
AppOnlyReadScope	Type	depends on type	X	X
AppOnlyUpdateScope	Type	depends on type	X	X
AppOnlyDeleteScope	Type	depends on type	X	X

Having this metadata in place will allow to throw meaningful exceptions when:

• Calls are made with app-only to types not supporting it
• LINQ queries are written that generate in failing queries (we could add some intelligence and for example leave out $top=1 and then take the first result when $top is not supported)
  • For $filter we would also need a way to only allow certain operators (eg eq)
• Calls are made without the required scope (if not set on a type then no scope checks are done)

We could implement above via 3 new attributes (using 2 base class attributes):

• SharePointPermissionsAttribute and GraphPermissionsAttribute for the app-only and scope related settings. This attribute must be applicable on the type but also on a method on the type. Method permissions would be added on top of a selected base type scope
• GraphODataAttribute for the odata related property settings for Graph

Samples:

# SharePoint Permissions on List type
[SharePointPermissions(
DelegatedReadScope = 'AllSites.Read', 
AppOnlyReadScope = 'Sites.Read.All',
DelegatedCreateScope = 'AllSites.Manage', 
AppOnlyCreateScope = 'Sites.Manage.All',
DelegatedUpdateScope = 'AllSites.Write', 
AppOnlyUpdateScope = 'Sites.ReadWrite.All',
DelegatedDeleteScope = 'AllSites.FullControl', 
AppOnlyDeleteScope = 'Sites.FullControl.All')]

# Graph permissions on Term type
[GraphPermissions(
AppOnlySupport = false, 
DelegatedReadScope = 'TermStore.Read.All', 
DelegatedCreateScope = 'TermStore.ReadWrite.All',
DelegatedWriteScope = 'TermStore.ReadWrite.All',
DelegatedDeleteScope = 'TermStore.ReadWrite.All')]

# Permissions on method: this would mean the token need to have `AllSites.Read` and `Sites.Search.All` or higher
[SharePointPermissions(BaseScope = 'Read', DelegatedMethodScope = `Sites.Search.All`)]
public async ISearchResults SearchMethod()
{}

# Tell that the Title property can be used in an OData filter when that filter uses the eq operator
[GraphOData(SupportsFilter = true, SupportedFilters= "eq")]
public string Title { get => GetValue<string>(); set => SetValue(value); }

This applies to #38, #67 and #68.

Tagging @PaoloPia , @ypcode , @pkbullock and @JarbasHorst for awareness.

[ypcode]

That looks pretty well detailed to me and probably covering almost all the scenarios :) I adhere! Awesome thinking @jansenbe !