Metadata: Add Field Filter To Limit Fields To Return

[chaiwa-berian]

In certain situations the default views of the metadata can be too verbose. A client might only need a few fields from each object and want to remove unnecessary fields from the response. To discover which fields are available for each object please see the schema documentation for each object type.

The format for include/exclude should be very simple and should allow for infinite recursion. To filter at the "root" level we can just use the name of the field, i.e. ?fields=id,name which would only display the id and name for every object. For objects that are either collections or complex objects with properties on their own you can use the format ?fields=id,name,members[id,name] which would return id, name of the root(SILC Group), and the id and name of every SILC Group Member on that object. Negation can be done with the exclamation operator, and we can have a set of presets of field select (see below). Only JSON should be supported in the first version of the API.

Example: Get id and name on the SILC Group:

/api/silc_groups?fields=id,name,members[id,name]

Example: Get with an exclude for specific fields would be:
/api/silc_groups?fields=:all,!id,members[:all,!id]
where !id means return every other field except the id field

[chaiwa-berian]

To exclude a field from the output we can use the exclamation (!) operator. This should be allowed anywhere in the query and will simply not include that property (as it might have been inserted in some of the presets).

A few presets (selected fields groups) are available and can be applied using the ':' operator.

Operator	Description
	Include property with name, if it exists.
[, ...]	Includes a field within either a collection (will be applied to every object in that collection), or just on a single object.
!, [!	Do not include this field name, also works inside objects/collections. Useful when you use a preset to inlude fields.
, []	Include all fields on a certain object, if applied to a collection, it will include all fields on all objects on that collection.
:	Alias to select multiple fields. Three presets are currently available, see table below for descriptions.

[chaiwa-berian]

Preset	Description
all	All fields of the object

• | Alias for all
  identifiable | Includes id, name, code, createdAt and updatedAt fields
  nameable | Includes id, name, shortName, code, description, createdAt and updatedAt fields
  persisted | Returns all persisted property on a object, does not take into consideration if the object is the owner of the relation.
  owner | Returns all persisted property on a object where the object is the owner of all properties, this payload can be used to update through the web-api.

Example: Include all fields from SILC Group Members except SILC Groups:

/api/silcgroupmembers?fields=:all,!silc_groups

Example: Include only id, name and the collection of SILC Groups from a data set, but exclude the id from SILC Groups:

/api/silcgroupmembers/BfMAe6Itzgt?fields=id,name,silc_groups[:all,!id]
Example: Include nameable properties from all SILC Groups:

/api/silcgroups.json?fields=:nameable