Smart APIs require a consistent method for executing complex queries or filters against their engineering data. To specify context or further refine results, these filters may also accept input parameters, resulting in so-called parametric filters.
Discovery
A Smart API exposes parametric filters as specific OData resources, discoverable in metadata by BaseType. For example, if you review:
https://sam.spclouddave.com/SampleService/Sppid/v2/$metadata
you will find the following parametric filter:
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Com.Ingr.Sppid.V1">
.
<EntityType Name="ParametricFilter" BaseType="Com.Ingr.Core.V1.ParametricFilter" OpenType="true" />
You can search metadata for the parametric filter name (in this example, ParametricFilter)
to discover other features. The remaining references for metadata originate from the
URL shown above.
Execution
A parametric filter is bound to an OData Action named Execute{FilterTypeName} that defines the filter's input parameters, its return type, and is used to execute the filter.
The action for a parametric filter is discoverable in $metadata by its bindingParameter. The input parameters and return type are also available.
For example, the SampleService provides the following OData action:
<Action Name="ExecuteParametricFilter" IsBound="true">
<Parameter Name="bindingParameter" Type="Com.Ingr.Sppid.V1.ParametricFilter" Nullable="false" />
<Parameter Name="objectHierarchy" Type="Com.Ingr.Core.V1.ObjectHierarchy" />
<Parameter Name="objectTypes" Type="Collection(Edm.String)" />
<Parameter Name="queryExpression" Type="Edm.String" />
<ReturnType Type="Collection(Com.Ingr.Sppid.V1.Equipment)" />
</Action>
See Parametric Filter execution example for details.
Organization
A Smart API may choose to logically organize parametric filter(s) to help a client navigate and discover the resources. In this case, parametric filters are exposed as navigation properties, contained by another resource. Again, organizing parametric filters as navigation property collections is not required (but supported, when appropriate).
For example, the SampleService API exposes parametric filters relative to a Plant:
<EntityType Name="Plant" BaseType="Com.Ingr.Sppid.V1.PlantItem" OpenType="true">
.
<NavigationProperty Name="Filters" Type="Collection(Com.Ingr.Sppid.V1.ParametricFilter)" ContainsTarget="true" />
You may also encounter a "MyFilters" navigation property, representing a collection of favorite parametric filters for a user. When supported, you will find the collection exposed via the Me singleton. The SampleService does not implement this pattern, but when an API does support MyFilters, it appears similar to the following:
<EntityType Name="User">
<Key>
<PropertyRef Name="UserName" />
</Key>
<Property Name="UserName" Type="Edm.String" />
<NavigationProperty Name="MyFilters" Type="Collection(Com.Ingr.MyApp.V1.ParametricFilter)" ContainsTarget="true" />
</EntityType>
Scope
A parametric filter may be scoped by:
-
navigation property - a parametric filter bound to a resource via a navigation property collection is scoped by its parent resource. For example, the parametric filter in the SampleService is scoped by the Plant from which the filter is executed.
-
input parameters - provide an object hierarchy and/or object type(s) as input parameters to scope the results of a parametric filter.
-
OData query expression - you can also provide an OData query expression as an input parameter to further refine the results of a parametric filter.
See Parametric Filter execution example for details.
Documentation
Parametric filters document their execution details via OData instance annotations exposed on the parametric filter instance.
To request documentation for a parametric filter, query for one specific instance (by key) with the $format=application/json;odata.metadata=full OData format parameter. For example, using the SampleService as a guide, the call would look like:
GET https://sam.spclouddave.com/SampleService/Sppid/V2/Plants('Plant A')/Filters('1582')?$format=application/json;odata.metadata=full
In addition, you must include the following HTTP header on the request.
Header name: Prefer, header value: odata.include-annotations="*"
The response includes instance annotations that outline execution details, such as:
-
SupportedObjectTypes - what object type(s) may I specify to scope the response?
-
SupportedObjectHierarchies - what object hierarchies may I specify to scope the response?
-
SupportedParameters - what input parameters does the parametric filter accept?
-
SupportedQueryOptions - what OData query options may be specified to format the response?
-
ColumnDefinitions - detailed information about property returned in the response.