Property whitelisting

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"
}
Was this article helpful?
0 out of 0 found this helpful