Skip to content

Migration Guide for web‐api v7

Jump to bottom
Fil Maj edited this page Dec 13, 2023 · 20 revisions

This migration guide helps you transition an application written using the v6.x series of the @slack/web-api package to the v7.x series. This guide focuses specifically on the breaking changes to help get your existing app up and running as quickly as possible.

@slack/web-api v7 Changes

This release focusses on the type safety of Slack HTTP API method arguments provided by @slack/web-api. If you use this package in a TypeScript project, many of the HTTP API methods now have stricter argument typing, which hopefully helps guide developers towards proper argument usage for Slack's HTTP API methods.

If you use this package in a JavaScript project, no such guidance is provided and the breaking changes listed below do not apply to you.

This release broadly is composed of three significant changes to the web-api codebase:

  1. 🚨 Breaking changes to API method arguments for TypeScript users (not for JavaScript users),
  2. 📝 Adding a ton of new hand-written JSDocs to provide useful method-specific context and descriptions directly in your IDE, and
  3. 🧑‍🔬 Type tests for method arguments, formalizing some of the co-dependencies and constraints unique to specific API methods

Let's dive into these three sets of changes and begin with the 🚨 Breaking Changes 🚨 to make sure we set you all up for success and an easy migration to v7.

🚨 Breaking Changes (TypeScript users only) 🚨

🚨 All Web API methods no longer allow arbitrary arguments 🚨

Previously, the arguments provided to specific methods extended from a WebAPICallOptions TypeScript interface. This interface made all API arguments effectively type un-safe: you could place whatever properties you wanted on arguments, and the TypeScript compiler would be fine with it.

In v7, in an attempt to improve type safety, we have removed this argument. As a result, if you were using unknown or publicly undocumented API arguments, you will now see a TypeScript compiler error. If you really want to send unsupported arguments to our APIs, you will have to tell TypeScript "no, trust me, I really want to do this" using the // @ts-expect-error directive.

If you find an issue with any of our method arguments, please let us know by filing an issue in this project!

🚨 Many Web API methods have new, sometimes quite-specific, type constraints

Another change that only affects TypeScript projects. A full and detailed list of changes is at the end of this document, with migration steps where applicable.

📝 Adding JSDoc to methods and method arguments 📝

This one benefits both TypeScript and JavaScript users! Both API methods and API arguments are exhaustively documented with JSDoc. It includes the API method descriptions, mimicking the hand-written docs we have on https://api.slack.com/methods, as well as documenting each API argument and linking to relevant contextual documentation where applicable.

🧑‍🔬 Type tests for method arguments 🧑‍🔬

All of the above-mentioned new TypeScript API argument constraints are exhaustively tested under test/types/methods. When in doubt, read these tests to understand exactly what combination of arguments are expected to raise a TypeScript error, and which ones are not.

🚨 TypeScript API Argument Changes

Many of the API argument changes follow a similar pattern. Previously, API arguments would be modeled as a 'bag of optional arguments.' While this was a decent approach to at least surface what arguments were available, they did not model certain arguments well. In particular, API arguments that had either/or-style constraints (e.g. chat.postMessage accepts either channel and blocks or channel and attachments - but never all three) could not be modeled with this approach. This could lead developers to a situation where, at runtime, they would get error responses from Slack APIs when using a combination of arguments that were unsupported.

Moving forward, all of our APIs were exhaustively tested and the arguments to them modeled in such a way that would prevent TypeScript developers from using the APIs with an unsupported combination of arguments - ideally preventing ever encountering these avoidable runtime errors.

Without further ado, let's dive in the changes for each API:

admin.analytics.getFile

Previously, most arguments to this API were optional. Now, the specific combinations of type, date and metadata_only are more strictly typed to ensure only valid combinations are possible.

admin.apps.activities.list

  • component_type is no longer any string, but rather it must be one of: events_api, workflows, functions, tables
  • min_log_level is no longer any string, but rather it must be one of: trace, debug, info, warn, error, fatal
  • sort_direction is no longer any string, but rather it must be one of: asc, desc
  • source is no longer any string, but rather it must be one of: slack, developer

admin.apps.approve

You can no longer provide both request_id and app_id - this API will only accept one of these arguments.

Clone this wiki locally