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"
}