Slackが採用するAPI設計の原則とプロセスを解説した記事が先頃、Slack Engineeringブログ上で公開された。記事にはSlackが、簡潔性、安全性、拡張性、開発者エクスペリエンスを念頭においてAPIを設計する上で使用する、6つの設計原則について説明されている。これらの原則を実践する方法として、4ステップのレビューとテストのプロセスが存在する。ただし、ある程度の融通は認められている。
筆者であるSaurabh Sahni、Taylor Singletary両氏はAPIの設計について、公開後に機能仕様を変更することは困難なので慎重に検討することが重要だ、という点を強調している。同社がこれまでにAPIの設計で犯したミスを認めた上で、氏らは、こうしたエラーが設計や開発者エクスペリエンスを改善する機会であることを指摘する。
さらに氏らは、"粗悪なAPIは企業の債務になる"としながらも、APIスタイルガイドの作成ですべてが解決する訳ではない、と警告している。"[APIガイドによって]判断の誤りを完全になくすことはできません(...)が、オープンに、誠実に、明解さを持って意思決定する上では有益です。"
Slackの設計原則のリストは、ひとつのことを適切に実行するAPIと、開発者エクスペリエンスとから始まっている。最初の原則は、APIは特定のユースケースに集中することによって、より明解で、安全で、拡張性を持ったものであるべきだ、というものだ。
開発者がAPIのパーツを直感的に見つけて、シンプルなユースケースを構築できるように、APIは十分に設計され、文書化されていなければならない、と筆者らは考えている。エラー発生時には、開発者が原因を理解して、問題解決への第一歩を踏み出せるように、APIは必要な情報をすべて返す必要がある。
5番目の原則は、スケールとパフォーマンスに関するものだ。この点に関して筆者らは、大規模なコレクションのページネーション、大規模コネクション内に大規模コネクションをネストすることの回避、APIへのレート制限の導入といった、具体的なアドバイスを提供している。
筆者らが掲げる最後の原則は、重大な変更は避けるべきだ、というものだ。Slackは、"昨日動作したものは明日も動作するべきだ"という哲学の下で、変化は不可避であっても、重大な変更はやむを得ない場合に限られるべきだ、という認識を持っている。
設計の原則に加えて、筆者らは、Slackで使用しているAPI設計プロセスについても説明している。API設計を完成させたチームには、実装の前にレビューを受けることが求められる。レビュープロセスでは、設計が同社のガイドラインに沿っていることと、同社の構想と一貫性を持っていることが確認される。レビューステージにおいては、選択されたAPIの潜在的ユーザからのフォードバックも取り入れられる。この特別なフィードバックを、同社では、APIのどの面をリファインすべきかを理解する上で役立てている。
実装が完了したAPIは、限定されたユーザによるベータテストステージに移行する。このステージで提供されたインプットはすべて、リリース前のAPI改善のために使用される。
業界には、APIの開発はデザインファーストアプローチに従うべきだ、というコンセンサスがある。InfoQは先日のAPIファーストな設計アプローチに関するレポートの中で、複数のフィードバックステージを含めたアジャイル的なAPI設計法を提唱している。