In order to be minimise network traffic and help avoid API rate limits, the HipChat API provides title expansion. This works by allowing clients to use the 'expand
' query parameter to instruct HipChat what entities and sub-entities to "expand" into the request.
The 'expand
' query parameter allows a comma-separated list of identifiers to expand. For example, the value 'modules,info
' requests the expansion of entities for which the expand identifier is 'modules
' and 'info
'. You can use the dot notation to specify expansion of entities within another entity. For example 'items.user
' would expand the 'items
' entity and the 'user
' entities within each item.
Any entity which contains a 'links
' property is eligible for expansion, and you can use other non-expandable properties to reach it. For example, let's say you wanted to retrieve information about a room named "Engineering". This would be your query:
1 2https://api.hipchat.com/v2/room/Engineering
The response would be something like this:
1 2{ "created": "2013-08-08T18:42:20", "id": 34, ... "participants": [{ "id": 375, "links": { "self": "https://api.hipchat.com/v2/user/375" }, "name": "Garret Heaton" }] }
Instead of needing to make a second request to get detailed information about Garret, you could expand your original query to include detailed participant info:
1 2https://api.hipchat.com/v2/room/Engineering?expand=participants
The response would be something like this:
1 2{ "created": "2013-08-08T18:42:20", "id": 34, ... "participants": [{ "created": "2013-08-08T18:42:20", "email": "garret@example.com", "group": { "id": 322, "links": { "self": "https://api.hipchat.com/v2/group/322" } }, "id": 375, "is_deleted": false, "is_group_admin": true, "is_guest": false, "last_active": "1379021231", "links": { "self": "https://api.hipchat.com/v2/user/375" }, "mention_name": "GarretHeaton", "name": "Garret Heaton", "photo_url": null, "presence": null, "timezone": "America/Denver", "title": "asdf", "xmpp_jid": "322_375@chat.foo.hipchat.com" }] }
Rate this page: