Standard practice
Building an OpenAPI 2.0 spec for the Slack Web API
The Slack Web API’s catalog of methods and operations now numbers nearly 150 reads, writes, rights, and wrongs. Its earliest documentation, much still preserved on api.slack.com today, often originated as hastily written notes left from one Slack engineer to another, in a kind of institutional shorthand. Still, it was enough to get by for a small team and a growing number of engaged developers.
Today we improve the bulk of that aging documentation by improving our response examples to be more evocative of reality and by introducing our first OpenAPI specification. Together, we hope these efforts will improve the platform’s accessibility and predictability.
OpenAPI 2.0 is an “open” API description language, previously known as Swagger. It’s a common, structured way to describe HTTP requests, responses, objects, authentication requirements, and other ways to map an API’s territory.
Our JSON-based OpenAPI spec lists all of our public Web API methods, instructs how to address them, which parameters and arguments they understand, example responses, and — for many methods — JSON schemas describing the exacting shape of data to expect from responses.
It should illuminate the Web API’s dark undocumented corners and enable you to build more resilient Slack apps. For those of you (like us) working with strongly-typed languages, it will help you build more robust libraries and SDKs. Have fun with it.
There are two ways to obtain this cool OpenAPI spec:
- Observe change over time by viewing or cloning the spec on GitHub.
- Download the most recent version of the spec from api.slack.com.
These first steps are only a beginning. We’re committed to expanding the breadth and depth of specifications we provide to illuminate data complexities and help you automate the perplexities of developing for the Slack platform.
How to use the spec
While we love to curl up at night and read a well-tabbed JSON document, there are even more useful ways to put this corpus to use:
- SDK development — By reflecting on our API spec’s predictably structured JSON document, you can train your software development kits and libraries to learn new Web API methods, their arguments, and response shapes automatically. Some will generate code and some will just evaluate at runtime.
- Postman — Postman is a focused HTTP agent that can superpower your API method testing. Just ask it to import our OpenAPI 2.0 specification. It might do everything you’ll ever need to do, without writing any code at all.
- Alternative forms of documentation — Don’t like reading the docs on api.slack.com? The OpenAPI community provides many tools to browse method docs your own way. Some will even help you generate sample code of varying utility.
- Mock servers — When developing new features or writing integration tests, it can be very useful to have a Slack to talk to that really isn’t Slack at all. Our API specification can be used with tools like Prism to quickly spin up a mock Web API server that responds with the examples embedded in the spec and documentation.
Code
Our spec currently weighs in at over 17,669 lines of uncompressed JSON. Here’s fewer than a 100 of those lines defining our most simple method, api.test.
How we built it
Our open Web API specification is an artifact. It’s the end result of an incredible machine (well, a Python script) compiling all the facts, fibs, schemas, and articulated examples across hundreds of individual files that describe our platform internally.
While I personally review the spec, validate it with a variety of many OpenAPI testing tools, and manually publish it to its homes on api.slack.com and GitHub, it is not a perfect reflection of Web API reality.
The OpenAPI 2.0 spec enables us to express many of the unique shapes, sights, and sounds of our organically grown RPC-based Web API, but it has some quirks that require us to editorialize actuality in order to be described. You can trust it, but verify.
Choosing OpenAPI 2.0 over alternatives
OpenAPI 2.0 is well-supported with a wide offering of open source tools, paid services, and engaging literature. It also has a helpful, experienced community behind it. OpenAPI 2.0 converts well into other specification formats, and is already familiar to many developers.
We considered a number of alternatives. One format we considered, API Blueprint, is the most human readable of all open API specifications, but it is best used as a key tool of our own API design rather than the humble output format we would misuse it as.
The initiative recently released OpenAPI 3.0, which is inarguably technically superior to 2.0, would provide remarkably more expressive descriptive possibilities for the entire Slack platform. With it, we’d be able to better describe webhooks, complicated response types, and our authentication patterns. I’m excited to describe the Slack platform in it, but OpenAPI 3.0’s tools and consumer-facing literature isn’t yet useful to you, the Slack developer.
We will one day offer OpenAPI 3.0 specs alongside 2.0.
Future releases
This is our first step in offering Open API specifications for all of our platform products. It is a living document.
In addition to ongoing JSON schema coverage and rich example responses in the Web API specification, we’re looking forward to providing developers with:
- An Open API v3.0 edition of the Web API spec, with more expressive JSON schema response structures and superior authentication descriptors.
- Specifications for incoming webhooks, interactive messages, slash commands, and the Events API
- Tighter specification presentation within api.slack.com documentation
- Example spec implementation in Slack’s own SDKs and tools
Gotchas
The OpenAPI 2.0 format itself, and our adoption of it, are not without a few quirks:
- OpenAPI 2.0 lacks adequate ways to describe passing OAuth 2.0 bearer tokens as Authorization headers. We don’t recommend using this spec to automatically generate OAuth 2.0 negotiation code.
- Some methods do not yet have full example responses provided. These methods will contain a simple success and error condition that mirrors the bare minimum responses returned by our API:
{"ok":true}or{"ok":false,"error":"invalid_auth"} - OpenAPI 2.0 tools and validators vary in what they consider “valid.” We validate our spec against as many tools as possible, but you will certainly find some tools or programming languages that disagree with the consensus we’ve found. Report issues to us, please!
- Due to many exquisite JSON schema descriptors being unsupported in OpenAPI 2.0, more complex JSON schema response objects are grossly over-simplified. Our future OpenAPI 3.0 spec will address these inadequacies.
Have fun, build stuff
Your comments and feedback on our Open API spec is welcome. Due to its generated nature, we can’t accept pull requests directly but instead must rework the incredible machine and its fodder to generate more helpful results. Send us your API specification wishes and miseries by filing an issue on GitHub. We welcome feedback on the API itself using the /feedback slash command or emailing us at feedback@slack.com.
If you’ve built something with our Open API spec, we want to hear about it! Tell us about your project on Twitter or email.
Our Web API’s canonical OpenAPI 2.0 spec is found on api.slack.com and GitHub. Learn more about OpenAPI.
