『APIデザイン・パターン』読書メモ
今回読んだのはこちら
APIに関してGoogleのAPI設計をもとにしたベストプラクティス集の本です
Amazonのレビューにもありますがちょこちょこは翻訳があやしいところはありました
概要
APIと一言に言っても実現したい処理が無数にあります
本書はそれぞれのケースに沿ってどういった考えで実装していけばよいのかを詳しく解説しています
結構分厚い本だったのですべてを書くと何回にも分けて書くことになりそうなのでかいつまんで書いていこうと思います
序盤
最初の方はデザインパターンを使うことでさまざまなケースに対応してAPIで処理を実現することができる
APIだとあとから名前などを変えるのは大変なので名前付けは重要
インラインと参照の話
リソースレイアウト図を書くといいですよ
などのお話が書いてあります
図を書いて関係図を理解することから始めるのは必要ですね
標準メソッド
GETやPOSTなどのあれですね
メソッドが用意されていない場合404ではなく405にするなどステータスコードもちゃんと用意することなど
冪等性の話もいつも通り書いてありました
deleteの冪等性はどっちにするのが良いのでしょうかね
削除すべきものがないのでエラーという考えもあるでしょうし削除自体はされているので成功とする、というのもわかります
このあとも色々なパターンが出てきますが基本的には標準メソッドを用意してパターンに応じて必要なカスタムメソッドを用意するなどのケースがほとんどとなっています
カスタムメソッド
上記で必要なカスタムメソッド、と書きました
これは標準メソッドだけで機能を実現しようとすることで副作用を引き起こし依存関係を作ることでAPIの質が下がらないよう別のAPIを用意するということです
便利な共通メソッドで作るというイメージではなく、あくまで標準メソッドでやると起きる副作用を切り出したもの、という位置付けで作成するものです
LRO（ロングランオペレーション）
処理が長くなってしまうものをAPIで処理するケースの話です
基本的に処理自体はバッチなどでもいいような気はしましたがAPIで実現するケースとして書いてありました
（というか後ほどバッチという章もあるので別物ではある）
LRO用のインタフェースを定義し処理が完了後に呼び出されたらDoneを返すようなイメージです
途中の経過などについての情報はどう残せばいいかなどは記載がなかったためそこは別途考えましょうということなんだと思います
本書はあくまでAPIの定義としてどういうインタフェースを提供するか、という話が書いてあるので細かい実現方法などは記載していません
多対多
リソース同士が多対多の関係を持つ時APIで実現する場合、add,removeというカスタムメソッドを追加することで関係性を管理します
この場合、実装上どちらかを親リソースとみなす必要があることと関係だけを保持する形になるため関連する情報を持つ場合は別途保存する必要があるなどのトレードオフがあります
関連情報を一緒に持ちたい場合は中間テーブルのようなアソシエーションリソースを作ることで実現する方法もあります
ページング
ページ分割を実現するAPIではpageToken,maxPageSize,nextPageTokenといった3つのフィールドを追加することで実現します
nextPageTokenによって次のページがあるかということがわかり要求することで次のページの取得が可能になります
ページングというと前のページやページ指定も考えられますがここではサポートしていません
それをサポートしようとすると最初に全てを取得する必要があり膨大なデータがあるとその取得に時間がかかってしまいページングをするメリットがなくなってしまいます（キャッシュなどの機構も必要になりそうです）
レスポンスの取得に失敗する場合
レスポンスが受け取れなかった場合リトライされるかもしれません
その場合に重複実行されても問題ないようにしておく必要があります
そこでリクエストに識別子を持たせて再リクエストされた時のために識別子に応じてレスポンスをキャッシュしておきます
その後実際のデータが更新されたかに依存せず実行時の結果を返すことになります
保持データが膨大になりそうですが、問題が起きるよりはハードで解決できるもののほうがマシという考えのようです
他にもたくさんの記載があったのでAPIを新規に定義する時には対象の場所を読み直してみるとよさそうです
この記事が参加している募集
この記事が気に入ったらサポートをしてみませんか？