An article explaining the API design principles and process used at Slack was recently published in the Slack Engineering blog. It explains the six design principles used at Slack to design their APIs while keeping simplicity, security, scalability and the developer experience in mind. A four-step review and testing process exists to enforce these principles, with some flexibility.
Saurabh Sahni and Taylor Singletary stress that it is essential to think carefully about the design of an API because it is tough to change or remove its behavioural contract once it is published. They acknowledge that the company has previously made mistakes in their API designs and point out that such errors are opportunities to improve the design and the developer experience.
The authors even go as far as to state that “bad APIs become a liability for a company” but at the same time caution that the creation of an API style guide is not a silver bullet. It “can’t completely save you from making crummy 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 more straightforward, safer and easier to scale.
The authors believe that APIs should be so well designed and documented that developers should be able to build a simple use case in a matter of minutes and discover parts of the API intuitively. In case of errors, the API should return all the information necessary for developers to understand the cause of the error and take the first steps towards solving it.
The fifth principle concerns scale and performance. The authors provide concrete advice, recommending pagination of big collections, avoiding nesting big collections inside other big collections, and implementing rate limiting on the API.
The last principle enumerated by the authors is that breaking changes should be avoided. Even though the philosophy followed at Slack is that “what worked yesterday should work tomorrow”, they acknowledge that change is inevitable, but breaking changes should be rare and unavoidable.
In addition to the design principles, the authors explain the API design process used at Slack. It requires teams to complete their API design and then have it reviewed before it is implemented. The review process helps ensure that the design is aligned with their guidelines and consistent throughout their landscape. During the review stage, additional feedback is requested from selected potential users of the API. Slack found that this extra feedback helps them understand which aspects of the API need refining.
Once implemented, the API enters a beta testing stage with a limited audience. Any input provided during this stage is used to improve the API before its release.
There is some consensus in the industry that the development of APIs should follow a design-first approach. InfoQ recently reported on an API-first design approach that advocates for an agile way of designing APIs that incorporates several feedback stages.