APIを自作する際の検討事項 - 30歳からのプログラミング

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のみであるため、AcceptがJSONを許可しない内容だった場合は、エラーを返す

これくらいだ。

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

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

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

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

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

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

エラー対応を考える

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