Well wishes and warnings in the Web API

Slack API
Slack Platform Blog
2 min readMar 21, 2016

Most of your calls to the Slack Web API succeed. You know this, `ok` is usually `true`. We have a bias to `ok`, and that’s all right with us.

Even with this open door policy, we can’t help but notice the occasional metaphorical mud on your shoes, or that your shirt is on inside-out. We wouldn’t turn you or your requests away, but we also wouldn’t have said anything — until now.

Recently, we added a Warnings section to Slack’s method documentation. Similar to its sister section, Errors, the new section lists the possible warnings potentially triggered by requests to an API method.

So when we receive a method call that we understand well enough to complete, yet we’ve identified some kind of problem with it, we’ll include a `warning` node in our response JSON, filling you in on how you could better formulate your request.

Let’s quickly review how this change may impact our responses to chat.postMessage.

You’ve sent Slack a perfectly formed missive, and we respond in kind:

{ "ok": true }

You’ve sent Slack a message we totally understood, but we had to make some assumptions about the request to service it:

{ "ok": true, "warning": "superfluous_charset" }

In this example, the warning indicates that you’ve sent us the right `Content-type` for the request, `application/x-www-form-urlencoded`, but you added an unneeded `charset` attribute.

In the rare case of a request generating multiple warnings, they will appear comma-separated within the warning value string:

{ "ok": true, "warning": "missing_charset,missing_content_type"}

Once rolled out, if you notice warnings in response to your requests, look up the meaning of the warning in the corresponding method documentation, and then revise your usage to correct it.

Today, only two minor warnings are defined: `missing_charset` and `superfluous_charset`.

We don’t think the additional`warning` field will negatively impact your applications and integrations. Please let us know if you anticipate issues parsing these otherwise successful responses.

We’d like to roll out the warnings feature within a month, along with additional, expressive warnings. Please follow @slackapi on Twitter and the #changelog to stay informed.

--

--

Slack API
Slack Platform Blog

Tips to integrate with Slack APIs to make your work life simpler, more pleasant and more productive — whether for your internal team or millions of Slack users.