Hipchat Connect versioning

There is a wide range of versions of the HipChat clients and HipChat server instances in usage at any one time. The HipChat connect API provides support for versioning to ensure your addon works correctly across servers and clients with different API versions. Versioning is opt-in, and will not affect your addon if you decide not to use it.

The API version support of the client and server are tracked using two separate integers:

• Server API Version - The version of the HipChat Connect API as understood by the server
• Client API Version - The version of the HipChat Connect API as understood by the client

These two numbers do not have any relationship, and will be incremented separately as functionality is added to either. Generally the numbers are used separately, but when used together they are separated by a ":" with the server version appearing first.

Minimum supported version

An addon is allowed to specify a minimum supported version for both the client and server, which will prevent your addon from being used if either of these requirements are not met. You should use this if your addon is unable to function in an old client or version of HipChat server. The minimum supported client / server version is specified in the root level of the descriptor with the key "apiVersion".

For example, to require a minimum server and client API version of 1 and 1 respectively, you would use the following descriptor's "apiVersion".

1
2
{
    "key": "addon.key",
    ...
    "apiVersion": "1:1"
    ...
}

Minimum Server Version

It is not possible to install an addon into a HipChat server instance if the requested server API version is not satisfied. If someone attempts to install an addon into an unsupported HipChat server version they will see an error:

Minimum Client Version

Your addon will not be loaded within the HipChat client if the client API version you requested is not satisfied. The addon will be marked as disabled within the integrations screen, and markers added to the room menu to show some addons have been disabled.

Supporting a range of versions

It is possible for an addon to support a range of versions, even if those versions have breaking changes. All calls to your service (including loading iframes) will include an API version which your addon is able to use to gracefully degrade if necessary.

API calls from server

All calls from HipChat's infrastructure to your addon are annotated with the version of the server making the call. This can be used by your addon to ensure your response is in a format understood by the server.

For example when installing an addon with the following installable component in their descriptor:

1
2
{
    ...
    "installable": {
        "callbackUrl": "https://www.example.com/install",   
    }
    ...
}

The following URL would be called during installation / uninstallation:

https://www.example.com/install?connect_server_api_version=1

API calls from client

Likewise calls from the client are also annotated with the supported connect client api version. For example the following glance:

1
2
{
    ...
    "glance": [{
        ...
        "queryUrl": "https://www.example.com/glance",
        ...
    }],
    ...
}

Would result in the following API call being made when fetching the glance data:

https://www.example.com/glance?connect_client_api_version=1

Querying the current server API version 

The connect API version of a HipChat server can be determined by querying it's capabilities document. For example querying www.hipchat.com/v2/capabilities returns:

1
2
{
    ...
    "connect_server_api_version": 1,
    ...
}