APIを自作する際の検討事項

7月に公開を開始した食品栄養素検索サービス『Food Health』、そのAPIを作った。

今後もAPIを作ることがあるかもしれないので、設計作業の流れを備忘録としてまとめておく。

機能を決める

まず、そのAPIでどんな機能を提供するのか、それを決める。

日本食品標準成分表2015年版(七訂)の内容をJSONで取得できる、というのが提供したい機能だ。
この成分表がPDFとExcelファイルでしか提供されていないことへの不満が、元々の動機。

ただ、その機能だけでは使い勝手が悪いので、検索機能も提供する。

検索機能で食品を探し、そこで得られた食品番号を使ってそれぞれの食品のデータにアクセスする。
これが、基本的な使い方になる。

エンドポイントを決める

WebAPIの場合、エンドポイントはURLで表現される。
そのため、APIで用いるURLや、そのルールを決める。
今回は、食品データを表現するリソース(食品リソース)と、検索結果を表現するリソース(検索結果リソース)にアクセスする、2つのURLを用意した。

バージョン管理をどうするか

バージョン管理が必要なのはAPIに限らないが、APIはプログラムを相手にするため、特に重要になる。
安易な変更や破壊を行うと、APIを利用しているプログラムが動かなくなってしまう。
そういった状態を防ぐためには、最初の設計が重要になる。
今回は、URLにバージョン番号を含む設計にした。

リクエストの方法を検討する

APIを利用する際にどのようなリクエストを送ってもらうのかを決める。

これも奥が深い分野ではあるが、今回のAPIはかなりシンプルなものであり、機微情報を扱うこともないので、ほとんど決めることはなかった。

  • 性質上、ユーザーによるリソースの追加や変更は有り得ないのだから、HTTPメソッドはGETのみを許可する
  • レスポンスのデータフォーマットはJSONのみであるため、AcceptJSONを許可しない内容だった場合は、エラーを返す

これくらいだ。

レスポンスの内容を決める

ヘッダとボディ、それぞれ。

ヘッダについては、Content-Typeと、キャッシュについて記述する。
それから、セキュリティに関するものをいくつか。

レスポンスボディは、先述の通りJSON形式とするが、具体的にどのような構造にするのか。

食品リソースについては、元となるデータがテーブル形式であるため、単純にそれをJSONのフォーマットに置き換えればよかった。

検索結果リソースについては、もう少し検討が必要だった。特に、ページネーションをどう表現するのかについて。
データ構造としての分かりやすさも大切だし、パフォーマンスについても考えないといけない。
今回は全体のデータ件数が固定なのでパフォーマンスはあまり考えなかったが、CGMのようにデータが増えていくサービスのAPIは、大変だと思う。

エラー対応を考える

実際には、食品リソースと検索結果リソースの他に、もう一つ、表現すべきものがある。
それがエラーメッセージ。
今回はシンプルなAPIなので、適切なステータスコードを返し、レスポンスボディで自然言語のメッセージを伝えることにした。
大手サービスのAPIでは、サービス固有のエラーコードを用意したり、それについて解説しているURLをレスポンスに含めたりしている模様。

想定されるエラーケースの列挙

どういったエラーが起こりうるかを洗い出し、それに対してそれぞれどんなステータスコードやメッセージを返すのか考える。
ここでしっかり洗い出しておかないと、実装の際にあれこれ考えて面倒になる。
精神的な負担感を減らすためにも、最初に列挙しておいたほうがいい。それでも、漏れは出てくるものだけど。

キャッシュ

キャッシュの管理方法についても考える。
今回は、サービスの性質上リソースの内容が変更されることは稀であるため、長くキャッシュすることにした。

セキュリティ

通常のウェブサービス同様、XSSSQLインジェクションに対して、対策を行う。
『Food Health』はユーザーによる投稿や機微情報の管理は行わないため、やるべきことは自ずと限定される。

参考文献

この2つは大いに参考になった。
特に『Webを支える技術』は、ウェブプログラミングを勉強する人なら、必ず読んだほうがいい。