Evolving the Slack API

You know how to design a good API, but how do you evolve that API when it’s time to make changes? We’ve faced this with each major feature release here at Slack over the past few years, most recently while working on the highly anticipated Shared Channels feature. Using shared channels, two organizations connect directly…

Slack logo
Slack
•
Brenda Jin
•8 min read•intermediate•
--
•View Original
ChefJavaScriptJSONOAuth

Overview

The article discusses the evolution of the Slack API, particularly focusing on the introduction of the Conversations API to support Shared Channels. It highlights the challenges faced during this transition and the improvements made to enhance developer experience and API functionality.

What You'll Learn

1

How to implement the new Conversations API for channel management

2

Why using smarter OAuth scope resolution simplifies API interactions

3

How to optimize API performance for large payloads

Prerequisites & Requirements

  • Understanding of API design principles
  • Familiarity with OAuth and API integrations(optional)

Key Questions Answered

What changes were made to the Slack API to support Shared Channels?
The Slack API was evolved to include the Conversations API, which unified the management of all channel types. This change was necessary to accommodate the unique requirements of Shared Channels, such as shared resources and varying privacy settings across workspaces.
How does the new OAuth scope resolution work in the Conversations API?
The new OAuth scope resolution allows developers to call conversations.info without needing to know the channel type. The API checks the requested channel type against the OAuth scope of the requester's token, returning a missing_scope error if unauthorized, thus simplifying app logic.
What performance improvements were made in the Conversations API?
The Conversations API introduced cursor-based pagination to handle large payloads more efficiently. This change was crucial for workspaces with over 10,000 channels and 150,000 members, addressing performance bottlenecks and reducing timeouts for large enterprises.
What is the significance of strict JSON Schema validation in the new API?
Strict JSON Schema validation ensures that API outputs remain consistent and reliable, preventing issues caused by unintended changes in core libraries. This validation improves the overall developer experience by minimizing bugs related to API inconsistencies.

Key Statistics & Figures

Maximum response payload size for channels.info
290MB
This size was observed for channels with a large number of members, highlighting the need for improved performance strategies.
Percentage of requests specifying no_members=true for channels.info
72%
This statistic indicates a common preference among developers to exclude member data in responses, which informed the design of the new API.

Technologies & Tools

Some links below are affiliate links. We may earn a commission if you make a purchase.

Authentication
Oauth
Used for managing permissions and access control in the Slack API.
Validation
JSON Schema
Employed for ensuring consistent API output and improving reliability.

Key Actionable Insights

1
Adopt the Conversations API to streamline your Slack app development process.
Using the new API can help reduce complexity in managing different channel types and improve the overall performance of your application.
2
Implement smarter OAuth scope resolution to enhance security and user experience.
By leveraging the new OAuth checks, you can ensure that your app only accesses the data it is authorized to, which is crucial for maintaining user trust.
3
Utilize cursor-based pagination for handling large datasets efficiently.
This approach not only improves performance but also helps in managing API rate limits effectively, especially for applications dealing with extensive user bases.

Common Pitfalls

1
Failing to account for the differences in channel types when using the old API.
This often led to unauthorized access errors and complicated app logic. Developers should transition to the Conversations API to avoid these issues.

Related Concepts

API Design Principles
Oauth Authentication
JSON Schema Validation
Performance Optimization Techniques