Field-Level Filtering

Field-level filtering lets you control which fields are included in a response. By returning only the required fields, you can improve performance and reduce network usage. APIs that support field-level filtering provide a fields query parameter to specify the fields to return.

Fields Query Parameter

The fields query parameter takes a comma-separated list of fields to include in the response. Any fields not included in the fields query parameter will come back as undefined.

To understand how the fields query parameter works, let's look at an example request to the Get User API:

GET https://yourapp-yourorg.us.wristband.dev/api/v1/users/123?fields=id,givenName,lastName 

In this case, the fields query parameter includes the following three user fields: id, givenName, and lastName. Therefore, the returned user response would only include those three fields as shown below:

{
  "id": "x63nnomvwrgqhgd2ofpdt3uk5e",
  "givenName": "Bob",
  "familyName": "Smith"
}

Nested Fields

Some Wristband resources have nested JSON structures. You can use path expressions in the fields query parameter to include specific nested fields. For example, to call the Get Identity Provider API and return only the protocol type (nested under the protocol object), you would use the path expression protocol.type as shown below:

GET https://yourapp-yourcompany.us.wristband.dev/api/v1/identity-providers/123?fields=protocol.type

The returned response would be:

{
  "protocol": {
    "type": "OAUTH2"
  }
}

Special Cases

• Include All Fields: To include all fields in the response, you can either omit the fields query parameter from the request, or you can use the * wildcard character like: fields=*.
• Exclude All Fields: To exclude all fields in the response, include the fields query parameter in the request, but leave its value blank, like: fields=