API design principles and process at Slack

An article explaining the API design principles and processes used at Slack was recently published on the Slack Engineering blog. It explains the six design principles used at Slack to design their APIs while keeping simplicity, security, scalability, and developer experience in mind. A four-step review and testing process exists to apply these principles, with some flexibility.

Saurabh Sahni and Taylor Singletary point out that it is essential to think carefully about the design of an API because it is difficult to modify or remove its behavioral contract once it is published. They recognize that the company has made mistakes in the design of its APIs in the past and point out that those mistakes are opportunities to improve the design and the developer experience.

The authors even go so far as to claim that “bad APIs become a liability for a business”, but at the same time warn that creating an API style guide is not a silver bullet. It “can’t completely save you from making lousy decisions (…), but [it] will help you make decisions openly, honestly and with clarity.

Slack’s list of design principles begins with each API doing one thing well and the developer experience. The first is that APIs should focus on a specific use case, thus becoming simpler, more secure, and easier to scale.

The authors believe that APIs should be so well designed and documented that developers should be able to create a simple use case in minutes and learn parts of the API intuitively. In the event of an error, the API should return all the necessary information for developers to understand the cause of the error and take the first steps towards its resolution.

The fifth principle concerns scale and performance. The authors provide actionable guidance, recommending paging large collections, avoiding nesting large collections within other large collections, and implementing rate limiting on the API.

The last principle listed by the authors is that ruptures must be avoided. Even though the philosophy followed at Slack is that “what worked yesterday should work tomorrow”, they recognize that change is inevitable, but disruptive changes should be rare and unavoidable.

In addition to design principles, the authors explain the API design process used at Slack. This requires teams to complete their API design and then have it reviewed before implementing it. The review process helps ensure that the design is aligned with their guidelines and consistent across their landscape. During the review stage, additional feedback is requested from selected potential users of the API. Slack found that this additional feedback helped them understand what aspects of the API needed to be refined.

Once implemented, the API enters a beta testing phase with a limited audience. Any input provided during this step is used to improve the API before it is released.

There is some industry consensus that API development should follow a design-driven approach. InfoQ recently reported on an API-centric design approach that advocates an agile way of designing APIs that incorporates multiple stages of feedback.

Abdul J. Gaspar