OData Query Parameters
The OData query parameters that Windchill REST Services support can be used in the following situations:
• When you access the entity sets defined in the domain
• When you navigate to a collection of entities from a given entity
• When you expand navigation properties of entities
Windchill REST Services support the following query parameters from the OData standard:
• $filter—Query criteria to filter the entities in a collection. When you access an entity set, an expression can be specified in the $filter query parameter. With the expression, you can restrict an entity set to only show entities for which the expression evaluation results to true value. OData supports filter expressions for a broad range of primitives. The framework only supports the following subset of OData expressions:
◦ Expressions that use String, Int16, Int32, Int64, Boolean, DateTimeOffset, Single and Double types
◦ Expressions that use comparison operators EQ, NE, GT, LT, GE, LE
◦ Expressions that use logical operators AND, OR
◦ Expressions that use unary operator NOT
◦ Expressions that use the methods startswith, endswith and contains
◦ Expressions that use the properties ID, CreatedBy, ModifiedBy, and View
|
|
The methods startswith, endswith and contains are not supported for the ID property. For example, $filter=contains(ID,'OR:wt.part.WTPart:112022') is not supported for the ID property.
|
OData enables services to specify the properties of an entity that must not be used in $filter expressions. OData services usually choose to restrict the use of certain properties in $filter expressions because of performance problems. The properties which are restricted for use in the $filter expressions are automatically specified by the framework for Windchill REST Services domains. The FilterRestrictions annotation defined in the Capabilities Vocabulary of OData is used to specify the restricted properties. This annotation is applied to the entity sets available in the domain and is seen in the EDM. Properties that are specified in this annotation are the nonpersistent or server calculated properties of Windchill.
The framework prevents properties specified in this annotation to be queried in the $filter expressions. If clients build query expression with these properties, the server returns an error message. For example, the sample below shows FilterRestrictions annotation applied to the Parts entity set:
|
|
It is recommended to apply filtering query criteria on entity set in a large dataset, otherwise it could increase the response time of the request.
|
• $select—Comma-separated list of entity properties that must be returned as a part of the response. For example, in the URL you can list the Document attributes such as, Name and CheckoutState, to display only the name of the document and its checkout status in the response.
• $expand—Used to specify the related resources that are to be included in line with retrieved resources. The value of $expand is a comma-separated list of navigations. Each expand item is evaluated relative to the retrieved resource being expanded.
For example, in this POST request you retrieve the component list for a part structure with the action GetPartsList. You can expand the navigation properties Part and PartUses to get more information about the components.
POST /Windchill/servlet/odata/ProdMgmt/Parts('OR:wt.part.WTPart:157919')/PTC.ProdMgmt.GetPartsList?$expand=Part,PartUses HTTP/1.1
FilterRestrictions (also known as NonFilterableProperties) are also enforced on Expanded Navigations. For example, $expand (UsedBy($filter=ObjectType eq 'Part') is not allowed will return HTTP 400.
$levels—This option is used along with $expand to specify how much information is fetched and returned to the client. The value of the $levels option is either a positive integer to specify the number of levels to expand, or the literal string max which is the maximum expansion level supported by the Windchill REST Services.
For example, when retrieving large structures, the $levels option limits how much information is returned. To limit structure expansion to N levels, specify $levels=N where N is a positive integer.
You can only expand multiple levels on a navigation property using $levels when the source type and target type are the same.
For example, calling /ProdMgmt/Parts('<oid>')?$expand=Uses($levels=max) will return an error while calling /DataAdmin/Containers(‘<oid>’)?$expand=Folders($levels=max) will return expected results.
You can fetch the navigation property on a derived entity with an expand option that has a type-cast segment to the derived entity. For example, a navigation property named RelatedDocuments is defined on ElectricalPart. When requesting a Part entity set, you can expand the RelatedDocuments navigation property on the derived entity ElectricalPart with the expand option that has a type-cast segment to the derived entity. Use the following GET request with the $expand query parameter:
GET Windchill/servlet/odata/ProdMgmt/Parts?$expand=PTC.ProdMgmt.ElectricalPart/RelatedDocuments
Similarly, when executing GetPartStructure action, you can expand the RelatedDocuments navigation property on the derived entity ElectricalPart with the expand option that has a type-cast segment to the derived entity. Use the following GET request with the $expand query parameter:
POST /Windchill/servlet/odata/ProdMgmt/Parts('OR:wt.part.WTPart:298122')/PTC.ProdMgmt.GetPartStructure?$expand=Part($expand=PTC.ProdMgmt.ElectricalPart/RelatedDocuments)
|
|
Typecasting in expand options in function results is not supported. For example:
/SavedSearch/SavedQueries('<OID>')/PTC.SavedSearch.ExecuteSavedSearch(Keyword='')?$expand=PTC.ProdMgmt.Part/Uses
|
• $top—Returns the specified number (N) of entities from the top, that is, the first N entities, in a collection.
• $skip—Skips the specified number (N) of entities from the top of a collection, and displays the set of entities, N+1 entity onward.
|
|
The $top and $skip query parameters are not supported on:
• Actions that are not read-only—Actions for which isReadOnlyAction is set to false.
• Actions that are not pageable—Actions for which isPageable is set to false.
|
• $orderby—Sorts the entities in ascending and descending order. The query parameter is supported for the following:
◦ Primitive attributes—String, Boolean, Integer, Real Number (Double), Date and Time types. See the following sample URL:
//Windchill/servet/odata/ProdMgmt/Parts?$orderby=<Primitive Property> <asc/desc>
◦ Properties—ID, CreatedBy, and ModifiedBy. See the following sample URL:
//Windchill/servet/odata/ProdMgmt/Parts?$orderby=<Property> <asc/desc>
◦ Complex types—The following properties of a complex type support sorting:
▪ QuantityOfMeasureType—Supported for value property. The properties Unit, Precision, and Display do not support sorting.
▪ EnumType—Supported for InternalName property. The property Display does not support sorting.
▪ Hyperlink—Supported for URL property. The property Label does not support sorting.
See the following sample URL:
//Windchill/servet/odata/ProdMgmt/Parts?$orderby=<Complex Property>/<Property> <asc/desc>
OData enables services to specify the properties of an entity that must not be used in $orderby expressions. The properties which are restricted for use in the $orderby expressions are automatically specified by the framework for Windchill REST Services domains. The SortRestrictions annotation is used to specify the restricted properties. This annotation is applied to the entity sets and complex types available in the domain, and is seen in the EDM. $orderby is not supported for the following properties. These properties are specified by the framework in the SortRestrictions annotation:
◦ Nonpersistent or server calculated properties of Windchill
◦ Properties of complex types that do not support sorting
The framework prevents properties specified in this annotation from being queried in the $orderby expressions. If clients build query expression with these properties, the server returns an error message.
For example, the sample below shows SortRestrictions annotation applied to the QuantityOfMeasureType complex type:
• $count—Returns the number of items in a collection. When you specify the $count parameter in the URL, it is mandatory to specify the value as either true or false. If no value is specified, an error message is returned.
The count is returned in the response body as "@odata.count": <count_value>.
The following URLs support $count:
◦ URLs for direct entities
◦ URLs for navigation properties
◦ URLs for expanding navigation properties
◦ URLs for structural properties
For example, in the following URL $count is specified as true. The URL returns the count of all the parts available on the server.
ProdMgmt/Parts?$count=true
