Title expansion

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.

What can I expand?

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:

https://api.hipchat.com/v2/room/Engineering

The response would be something like this:

{
  "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:

https://api.hipchat.com/v2/room/Engineering?expand=participants

The response would be something like this:

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