適切なAPIを設計するために注意したいこと「バージョン管理、同期・非同期」

アプリ、Webサービスと数多くのインターネットを使ったサービスが登場するのに比例してWeb APIも次々と作られています。Web APIのマーケットが拡がっていくことで認知が高まり、さらにWeb APIが開発されていくという好循環が生まれています。

その一方で乱立することによって、Web APIの品質が問題になってきます。Web APIではWebブラウザを使ったアクセスとは異なり、基本的にプログラムからのアクセスを考えなければなりません。そのため不用意なセキュリティホールがあったりすると、あっという間に大きな問題（データの消失であったり、乗っ取りであったり）が発生する可能性を秘めています。

そこで私たちはWeb APIの設計に際して標準規則を策定しています。その規則に沿ってWeb APIの開発を進めることで、可用性はもちろん堅牢性や安全性を意識した情報の提供ができるようになります。これまでのインタフェース、データフォーマットに続き、今回は バージョン管理、同期・非同期 について規則の一部を紹介します。

バージョン管理について

Web APIのバージョン管理は常に話題にあがってきます。対応方法としては以下のパターンが考えられます。

1. URIのパスにバージョン番号を含める
2. URIのパラメータにバージョン番号を含める
3. 新しいWeb APIを作る

3.の新しいWeb APIを作る方法は機能の乱雑化を生みますし、メンテナンスコストを著しく悪化させるためお勧めできません。2.のパラメータに含める（/api?version=2など）はキャッシュの兼ね合いやロジックの複雑化につながる可能性があります。

そこで私たちはURIのパスにバージョン番号を含める方法を基準としています。つまり次のような形です。

https://example.com/v1/api

v1がバージョン番号にあたります。こうすることでWeb APIの実装が大幅に変更された場合においても下位互換性を維持することができます。

同期・非同期の分け方について

Web APIの場合、クライアントからネットワークを使ってアクセスしてきますので、あまり長時間のネットワーク接続が求められるものはタイムアウトしてしまう可能性があります。そのため最長でも30秒程度までを同期処理、それ以外は非同期処理として実装するのが良いでしょう。

エンタープライズレベルでのWeb API実装においてはトランザクション処理が求められることが多々あります。しかしHTTPを使ったネットワークとトランザクションは相性が良くありませんので、トランザクションを用いた処理の場合は非同期処理を用いるのが良いでしょう。

Web APIは一度作ったら終わりではなく、随時更新、変更されていくものです。この点においては通常のWebサービス、Webシステムと同様と考えられます。ただしWebサービスなどはUIを変えても利用者が使い方を習得してくれる一方、Web APIはリリース後は自動運転されることが多いので旧来の接続クライアントに常に気を配っておく必要がある点を注意してください。

ぜひ皆さんのWeb API設計において参考にしてください。