REST API設計のパターンと原則

2022年10月25日 16:31

APIの設計って意外と移り変わりがあるんです。例えばAPIのバージョンの指定方法がヘッダーを使う方法からURLを使う方法にだんだん統合されてきました。

したがって本やスライドなど、その時点のベストプラクティスを読むよりは、生きているベストプラクティスを読んだ方が良いと思います。

ここではいくつか参考になるリソースのご紹介と、よく聞かれる質問について触れておきます。

設計ガイドライン、スタイルガイド

APIの設計のベストプラクティスを把握するためによくAPIのドキュメントを見ているのですが、特にご紹介したいのはスタイルガイドや設計ガイドです。

マイクロソフトのAPIガイドライン

GoogleのAPIスタイルガイド

APIポータルなども良いと思います！
APIポータルを見ると、このAPIプログラムはどのようにAPIクライアント開発者を捉えているかが分かります。

お気に入りはGoogle Map APIです。ポータルの作りがときどき変わるんですが、Time to Hello World (最初のAPIリクエストを送るまでの時間) を意識されているのが分かります。

ガイドラインではないですが、SalesforceやServiceNowなどのaPaaSのAPIはジェネリックに作られていて面白いです。

よく聞かれるんですが、APIはあまり大量データの扱いが得意ではありません。レイテンシーの問題になったり、サーバーのパフォーマンスの問題になったりするので、仕方なく扱うことはありますが、選択肢があるならAPIで大量データを扱わなくてもいいようにすることです。

大量データを取得したいのは何の目的でしょうか。

よく出るのは分析目的でデータをCSVで欲しいなどの場合です。こういう大量データの扱いの目的に応じて適切なシステムを用意してあげる方が良いと思います。分析ならBIです。データ同期であれば定時バッチを使った同期やイベント連携などをご検討ください。

本当にAPIで扱わなければいけないとして、問題になるのはページネーションです。1万件レコードがある中の「ここからここまでデータください」というやつです。

これはデータやアプリケーションの特色と、どういうソート順でAPIクライアントがデータを欲しいかによって大きく設計が変わるところですので、残念ながら「これだけ覚えておけば大丈夫！」というものはありません。

問題になりがちなのが、データの順序が頻繁に入れ替わる、あるいは新しいデータがどんどん作られる環境で、もれなくダブりなくどうやってデータを取得することができるようにするか、です。

TwitterのAds APIではどんどん新しいデータが作られるからかと思いますが、「cursor」を使ってどこまで取得済みかがわかるようにしています。

このように似たようなデータの傾向を持つAPIの実装を調べていただくことをお勧めします。

ここ数年のトレンドとして、以下は言えると思います。