Property whitelists are used to limit the properties of resources in the server response. This is mainly useful for reducing data overhead.
When using a whitelist, only the properties specified by the whitelist are returned, except for EID
and type
which are always returned when applicable. It’s also worth noting that next to these two properties all reserved HAL properties will also always be returned.
Query Parameters
Name | Type | Value |
---|---|---|
properties[ path ] | string | Comma-separated list of property names |
Adding a path to the properties parameter is optional. Without a path, the whitelist applies to the main resource being requested. You can apply the whitelist to an embedded resource by specifying a path that matches the embedded relations as specified using the embed parameter.
Syntax
property path = [ resource ], { ".", ? resource name ? } ".", ? property name ? ;
resource = "self" | ? resource name ? ;
Example
https://api.speakap.io/networks/fedbca0987654321/messages/1234567890abcdef/ ↵
?properties[messages]=messageType ↵
&properties[messages.author]=fullName,primaryEmail
{
"_links": {
"author": {
"href": "/networks/fedbca0987654321/users/abcdef0123456789/"
},
"comments": {
"href": "/networks/fedbca0987654321/messages/?parent=1234567890abcdef"
},
"like": {
"href": "/networks/fedbca0987654321/messages/1234567890abcdef/like"
},
"likers": {
"href": "/networks/fedbca0987654321/messages/1234567890abcdef/likers/"
},
"recipient": {
"type": "network",
"href": "/networks/fedbca0987654321/"
},
"self": {
"href": "/networks/fedbca0987654321/messages/1234567890abcdef/"
}
},
"_embedded": {
"author": {
"_links": {
"avatar": {
"href": "/networks/fedbca0987654321/messages/9876543210abcdef/"
},
"network": {
"href": "/networks/fedbca0987654321/"
},
"self": {
"href": "/networks/fedbca0987654321/users/abcdef0123456789/"
},
"settings": {
"href": "/networks/fedbca0987654321/users/abcdef0123456789/settings/"
}
},
"type": "user",
"EID": "abcdef0123456789",
"fullName": "John Doe",
"primaryEmail": "johndoe@gmail.com"
}
},
"type": "message",
"EID": "1234567890abcdef",
"messageType": "update"
}