API設計の原則と現実のギャップを埋めるには
まず草薙氏は、API設計に適した開発プロセスについて議論する。多くの現場では、APIを実装しながら設計して、コードのコメントなどをもとに、ツールでOpenAPI形式の仕様書を出力して、補足文を付け足す。そんな流れでAPI開発が進んでいくことが多いのではないだろうか。しかし、このやり方では、仕様やドキュメントと実装が乖離してしまい、将来的には技術的負債になることが多いと、草薙氏は問題提起する。
そこで草薙氏が勧めるのが、API仕様を先に決めてから開発する、APIファースト開発というアプローチだ。まずAPIで実現したい機能について、API開発者と利用者が、技術・ビジネスの両面から検討し、合意を得る。この合意は、APIコントラクトと呼ばれ、強い拘束力を持つ取り決めだ。APIコントラクトをもとに仕様書を作成し、モックとテストを用いて仮説を検証し、想定どおりに動作するか検証する。そして最新の状況を反映しながら、開発、テスト、実装、ドキュメント作成のイテレーションを繰り返して開発を進めるスタイルだ。
続いて、良いAPI設計が従うべき原則とは何だろうか。草薙氏が勧めるのは、HTTPの標準仕様やRESTの原則に従うことだ。例えば、HTTPには、メソッドやヘッダ、ステータスコードなど、さまざまな規約が存在している。そしてAPIは、対象となるデータをURLで識別する統一インターフェースの使用、クライアントとサーバの分離、ステートレスな動作を行うといったRESTfulな振る舞いをするのが望ましい。これらに従うことで、利用者の学習が容易になり、バグの混入の防止、パフォーマンスの最適化、再利用性の向上など、さまざまなメリットが生じる。またスケーラブルで、Webのパフォーマンスを引き出す実装を、自然に行うことが可能になる。
しかし現実のAPI設計では、原則だけではうまくいかないケースがつきものだ。多くのAPIで使われている、現実的な実装にも目を向けるべきだと、草薙氏は指摘する。特にポピュラーなサービスのAPI設計には、開発者の試行錯誤や深い議論が反映されている。こうした知見を取り入れることで、より優れたAPIを設計できると、草薙氏は言う。
そこで草薙氏が紹介したのは、欧州の大手ファッションECサイト Zalandoが公開したRESTful API設計のガイドラインだ。基本的にはRESTの原則に従いつつ、自社のサービスの特性に合わせてルールを決めている好例だと草薙氏は言う。Zalandoの他にも、さまざまな企業が、API設計のガイドラインを公開している。それらを参考にしながら、「自社のビジネスに合わせて、それぞれの現場でAPI設計ガイドラインを決めて、それを守りながら開発を進めるのがおすすめだ」と、草薙氏は言う。
次のページでは、それらのAPI設計ガイドラインの中から、代表的なポイントを抜粋して紹介する。
