extraParams Service Parameter

Most resource provider services for creating, reading, and updating resources allow one to adjust the results via an "extraParams" service parameter. This parameter is a JSON object which conveys optional information to the service in question.

$skip and $top

The $skip entry in the "extraParams" parameter specifies a number of resources that should be skipped or omitted from the start of the results. This capability is inspired by and analogous to OData's $skip option.

The $top entry in the "extraParams" parameter specifies the maximum number of resources that should be returned. Resources after this limit are reached are omitted from the results. This capability is inspired by and analogous to OData's $top option.

For more information about Odata’s $skip and $top options, see www.odata.org.

All resource providers are expected to support these features on the Get service. The Resource Manager supports these features on its Get and CallServiceByCriteria services, contingent on the resource providers it delegates to doing so as well. The default implementation of the InflateFromRole service on RelationshipServiceProvider supports these features as well, as long as the Get service on the resource provider supports them (as the default InflateFromRole implementation delegates to Get).

$expand

ResourceProvider services which support "extraParams" support use of "$expand" as a key to request that the resource fields returned be augmented with "expanded" information from related objects. This capability is inspired by and analogous to OData's expand option. Each expanded roles results in an additional result field named after the expanded role and containing InfoTables of related objects' fields.

A simple $expand value can simply be a string containing a comma-delimited list of relationship roles to expand to. For instance, you might have "Owner,Operator" to expand related Owner and Operator roles. Also, all related objects are returned for each selected role and in no particular order -- one cannot filter out objects which are not of interest, nor sort them.

The more powerful alternative is to specify a JSON object value for the $expand key. Each key within this object is the name of a role to expand. The values within this JSON object are themselves JSON objects. Within these objects, "dataShape" and "query" are supported as optional keys. The overall JSON looks something like the following:

{
  $expand: {
    Owner: {
      dataShape: {
        ....
      },
      query: {
        ....
      },
      $expand: {
        ....
      }
    },
    Operator: {
      ....
    }
  }
}

The actual behavior and contents of the "dataShape" and "query" values are detailed in the following table.

Value	Description
dataShape	The "dataShape" key defines the fields to select from the expanded role via a ThingWorx data shape. The value of the field can either be the name of a persistent ThingWorx data shape entity or the JSON object form of a ThingWorx DataShapeDefinition.
query	The "query" key defines a ThingWorx Query to filter and/or sort the expanded role results. The value of the field must be the JSON object form of a ThingWorx Query.
Nested $expand	An "$expand" key nested within an outer $expand key indicates an expansion to be performed upon the expansion results themselves. The format of this element is the same as $expand.