Itemize and Advise on Good APIs. Comparing Slack and HipChat from a developer’s perspective

What makes a good API, the kind that developers will jump at the chance to work with? That’s something I’ve had plenty of time to ponder as we’ve built Lucidchart add-ons for Slack and HipChat over the past year. While both messaging apps offer similar features to users, they provide surprisingly different APIs to developers. Based on my experience developing apps for these APIs, here’s what to expect from each in terms of functionality, usability, and documentation. Your mileage may vary.

Functionality

An API needs to offer enough functionality to be useful. Exactly what an API should allow varies from product to product, but you can estimate an API’s usefulness by coming up with ideas for apps, then considering how plausible they would be to build. Ideally, an app should be able to get access to almost any action, but it may require approval to use the more sensitive ones via some sort of permission system.

HipChat

HipChat’s API involves a set of resources such as groups, rooms, and users. With the right permissions for your integration, you can manipulate all of them. Want to notify a room? Invite someone to a room? Upload a file? If a HipChat user can do it, chances are that your app can too. On top of standard actions, your app can listen to events like room creation or messages with specific keywords and use them as the basis for other actions. HipChat also offers extended functionality and GUI elements. Web panels, for instance, allow you to iframe web pages within HipChat, resulting in greater interactivity and visual appeal, and Actions allow your app to hook into the GUI, adding menu items that bring up dialogs or open external pages. You can also let users install your integration to a specific room, giving room creators the chance to try out your app without bothering the account admin, which is a great boon for getting your app out there.

That said, HipChat’s API does lack one essential feature: the ability for an app to directly message a user. There are workarounds, but it is more difficult than it should be (more on that later).

Slack

Slack’s API is organized much like HipChat’s. It also has a set of resources and a number of API calls to read or interact with them. In fact, Slack and HipChat’s resources and functionality are nearly identical. If your app just leverages basic HipChat APIs, you’ll have no trouble recreating it in Slack. In terms of extended functionality, Slack doesn’t allow integrations to create any custom views, instead limiting apps to plain or lightly formatted text. As a result, complex integrations generally have a pseudo-command-line interface, requiring one command to display information and yet another to act upon it. As an example, when using the memebot app, I often forget the exact name required for the meme I want, and I have to type /meme-list to go to the page that lists them. With access to GUI elements, the developers of that app would be able to create something like an autocomplete search. On the plus side, Slack supports directly messaging users, which is something HipChat makes difficult.

The Verdict

HipChat offers a greater degree of customization and allows you to build more complex apps, but Slack is perfectly adequate for basic needs. This round to HipChat.

Usability

No matter how much of the functionality an API exposes for developers to tinker with, if it requires a confusing sequence of requests in nonsensical formats or forces you to find roundabout methods to complete simple tasks, then it’s not that useful. A good API considers and makes simple the kinds of actions developers will want to take and the data they’ll want to access. A good API also tries to follow common conventions if possible, as this helps developers quickly understand and use it.

HipChat

HipChat uses a RESTful API, where you use HTTP verbs like GET or DELETE to perform actions on a set of resources. As with other APIs, 2XX-level responses signify that things went well, 4XX responses mean that you did something wrong, and 5XX errors mean that the servers exploded. Most of HipChat’s API is fairly standard and easy to use. No surprises there. Example request:

curl -G -H "Authorization: Bearer <auth-token>" https://api.hipchat.com/v2/user/12345
{
  "created": "2015-12-15T17:36:43+00:00",
  "email": “exampleman@example.com",
  "group": {
  "id": 476618,
  "links": {
    "self": "https://api.hipchat.com/v2/group/54321"
  },
  "name": "example-team"
  },
  "id": 12345,
  "is_deleted": false,
  "is_group_admin": false,
  "is_guest": false,
  "last_active": "2015-12-15T21:22:39+0000",
  "links": {
    "self": "https://api.hipchat.com/v2/user/12345"
  },
  "mention_name": "ExampleMan",
  "name": "Example Man",
  "photo_url": "...",
  "presence": null,
  "roles": ["user"],
  "timezone": "America/Denver",
  "title": "Hero of Examples",
  "version": "...",
  "xmpp_jid": "..."
}

Less typical, however, is how difficult HipChat’s API makes it to get detailed information from a lot of resources at once. Take the get all users API call, which only returns a user’s ID and @mention name. If you want more detailed information, such as their email addresses, you have to make an additional API call for each user, which can quickly burn through your request limit (500 per five minutes). Added to that is the difficulty of messaging a user directly, as mentioned previously. There are only a couple of ways to do so, and none of them are attractive. First, you could get an authentication token from a user, then send someone a direct message on behalf of that user, but this won’t work if you want the message to appear as though it came from your app. You could get around this by asking the HipChat admin to create a user for your app to send messages from, but that increases the overhead to use your integration. Alternately, you could create a private room with the recipient and then push a message or notification to that room. This solution could lead to unwanted room clutter, and if you wanted to message that same user again, you’d have to take into account the original room, which limits your options:

1. Keep track of the private room you created and make sure they haven’t left it.
2. Instead of tracking the room, search the rooms they belong to, then create a private room if it doesn’t exist.
3. Deal with the fact that you create a room every time you want to message someone.

None of these options are particularly appealing. It would be much better if HipChat would automatically create a bot user for your integration to handle messaging.

Slack

In contrast with HipChat’s RESTful approach, Slack went with the method-oriented RPC style. Slack’s API includes the status of each request in its responses alongside any other data appropriate for the request, which makes it resemble some sort of mutated plushy animal. But it’s a friendly, strangely adorable plushy animal, because Slack also documents exactly what every API call is going to do, including every error and warning not related to a server meltdown. Here's an example.

curl -G https://slack.com/api/users.list?token=xxxx-xxxxxxxxx-xxxx
[{
  "id": "U1234567890",
  "team_id": "T1234567890",
  "name": "exampleman",
  "deleted": false,
  "status": null,
  "color": "8d4b84",
  "real_name": "Example Man",
  "tz": "America/Denver",
  "tz_label": "Mountain Daylight Time",
  "tz_offset": -21600,
  "profile": {
    "first_name": "Example",
    "last_name": "Man",
    "phone": "",
    "title": "Hero of Examples",
    ...
    "real_name": "Example Man",
    "real_name_normalized": "Example Man",
    "email": "exampleman@example.com"
  },
  "is_admin": false,
  "is_owner": false,
  "is_primary_owner": false,
  "is_restricted": false,
  "is_ultra_restricted": false,
  "is_bot": false,
  "has_2fa": false
},
...
]