Update filter-as-segment.md

Author: corranrogue9

graph/articles/filter-as-segment.md

@@ -1,3 +1,51 @@
 # Filter as segment
 
-There is an OData feature which allows 
+There is an [OData feature](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_AddressingaSubsetofaCollection) which allows having a `$filter` in a URL segment. 
+This feature is useful whenever there are operations on a collection and the client wants to perform those operations on a *subset* of the collection. 
+For example, the `riskyUsers` API on Microsoft Graph has an action defined to let clients "dismiss" risky users (i.e. consider those users "not risky"):
+
+```xml
+<Action Name="dismiss" IsBound="true">
+  <Parameter Name="bindingParameter" Type="Collection(self.riskyUser)" />
+  <Parameter Name="userIds" Type="Collection(Edm.String)" />
+</Action>
+```
+
+Using this action, clients can call
+
+```http
+POST /identityProtection/riskyUsers/dismiss
+{
+  "userIds": [
+    "{userId1}",
+    "{userId2}",
+    ...
+  ]
+}
+```
+
+in order to dismiss the risky users with the provided IDs. Using the filter-as-segment OData feature, the action could instead be defined as:
+
+```xml
+<Action Name="dismiss" IsBound="true">
+  <Parameter Name="bindingParameter" Type="Collection(self.riskyUser)" />
+</Action>
+```
+
+and clients could call:
+
+```http
+POST /identityProtection/riskyUsers/$filter=@f/dismiss?@f=id IN ({userId1},{userId2},...)
+```
+
+Doing this is beneficial due to the robust nature of OData filter expressions: clients will be able to dismiss risky users based on any supported filter without the service team needing to implement a new `dismiss` overload that filters based on the new criteria.
+However, there are some concerns about the discoverability of using the filter-as-segment feature, as well as the support of [parameter aliasing](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_ParameterAliases) that's required.
+As a result, functions should be introduced that act in the same way as the filter-as-segment:
+
+```xml
+<Function Name="userFilter" IsBound="true" IsComposable="true">
+  <Parameter Name="bindingParameter" Type="Collection(Microsoft.DirectoryServices.user)" Nullable="false" />
+  <Parameter Name="expression" Type="Edm.String" Nullable="false" />
+  <ReturnType Type="Collection(Microsoft.DirectoryServices.user)" />
+</Function>
+```