Introduction
This is a feature that allows the client to request that a specific set of information be returned by an API. This is especially needed for two main reasons:
-
reduce the subset of information that is returned, i.e. only return IDs;
-
request additional fields that are not returned by default, i.e. custom data added to resources.
To configure the desired fields, you can specify the _fields QueryParameter which is an array of strings where each string represents a response attribute.
Fields parameters
Request QueryParameters
The _fields parameter is a QueryParameter in which the client can specify a collection of strings representing the desired output fields. The format is the following: _fields=pippo&_fields=pluto&....
Response payload
The response payload will contain the following:
-
non-resource related data such as pagination information;
-
resource related non-optional data, which cannot be removed via the fields configurability feature;
-
information requested via the fields configurability feature, provided that the requested fields exist for the queried resource.
Hierarchical fields
There might be APIs in which the response is not merely a simple JSON Object but is composed by several nested objects. In these cases one can exploit the full potential of the output fields selection feature, by chaining together the objects names using a . (dot) to link two objects. Let us take an example to clarify the syntax: work-order.code selects the code field of the work-order object. This can be extended to any degree of nesting: work-order.operation.description selects the description field of all the operation objects of a work-order.
Example
Request
curl "<https://api.overit.cloud/api/r1/work-order?_fields=id&_fields=code>" \
-H "Authorization: Bearer <personal_access_token>"
Response
With fields configurability
"content": [
{
"id": 0,
"code": "string"
}
],
"_page": {
"num": 0,
"hasMore": true
}
Without fields configurability
"content": [
{
"id": 0,
"code": "string",
"description": [
{
"lang": "string",
"value": "string"
}
],
"order": 0,
"active": true,
"urgency": true,
"color": "string"
}
],
"_page": {
"num": 0,
"hasMore": true
}