API設計を行う際に注意したいこと（導入編）

Programming
2015/9/29

昨今、APIの重要性は高まるばかりです。プロジェクトの大小にかかわらず、APIはどこかで使われているのではないでしょうか。そこで今回はAPIの設計手順について見ていきたいと思います。APIをはじめて設計される方はもちろん、これまではなんとなく設計してきたという方もぜひご覧ください。

APIとRESTについて

最近、APIではよくREST APIや単にRESTといった単語が聞かれるようになっています。RESTとはHTTPプロトコル規格の主要著者の一人であるRoy Fielding氏が提唱したことで有名です。そのFielding氏のREST原則通りに構築されたシステムはRESTfulと呼ばれます。その経緯などの詳細はWikipediaに譲るとして、最近は以下のように包括されているようです。

  • Fielding氏のRESTアーキテクチャスタイルの原則に合わせたWebサービスシステム
  • RPCスタイルに合わせた簡易な XML+HTTP インターフェイスを採用したシステム（SOAPは使わない）

本稿では、RESTアーキテクチャスタイルの原則には沿っていません。また、APIをHTTPでのステートレスなクライアント・サーバプロトコルとして、包括的な話を進めていきます。

API定義書

API定義書は開発がはじまる前までに、たとえ資料の納品の必要がなかったとしても作成した方がいい資料です。現場サイドであらかた決めておくだけでも開発の進みやすさが違うでしょう。後から作成するなどといって先送りしてしまうと、後になって振り返りたくなってもできなくなってしまいます。

API定義書作成のベストプラクティスを上げるとすれば、コーディングとテストを行いつつ、それを定義書に落とし込めるツールになるでしょう。以下に主なツールを紹介しておきます。どれも一長一短ありますので、プロジェクトにあったツールを選定してみてください。

エンドポイントの設計

パスに含めるのはどれ？

パスやクエリパラメータに含める情報については、APIを構築する言語や利用するフレームワークよって左右されてしまうことがあります。例を紹介します。以下はどちらもユーザプロファイルを取得するAPIとします。109876はユーザIDです。

```
// 1．IDをパスに含めるケース
http://abc.com/v1/user-profile/109876

// 2．IDをクエリに含めるケース
http://abc.com/v1/user-profile?id=109876
```

この場合、ユーザIDをシステム側がどのように取得するかによるのですが、最近の開発言語でのフレームワークでは殆どが1のパターンをルーティング処理で対応できるようになっています。実際、1の方がメソッドでの項目利用やバリデーションのフック処理などで対応しやすいと思います。

ユーザIDなど特定のIDを検索するパターンならば上記で十分です。では、ユーザ一覧を取得する場合はどうでしょうか？ここでは、10件目から20件を取得するケースとします。

```
// 1．IDをパスに含めるケース
http://abc.com/v1/users/10/20

// 2．IDをクエリに含めるケース。offsetは何件目から取得するか、maxは取得件数を意味しています。
http://abc.com/v1/users?offset=10&max=20
```

1のケースはパッと見て何がしたいのか良くわかりません。このケースでは2の方が分かりやすいかと思います。

このように、操作内容によってどちらに含めるのかを考慮しましょう。基本的には、エンドポイントをデフォルトで接続した場合を考慮し、それ以外の操作は可変パラメータを渡すようにしましょう。

エンドポイントにはバージョンを含めよう

APIを広く一般ユーザへ公開する場合には、バージョンを含めましょう。このバージョンを入れることで、APIの切り替えなどがスムーズになります。多くのサービスをみると、バージョンはAPIサービス名のすぐ後に入れるのが一般的なようです。たとえば次のようになります。

http://abc.com/api/v1/…
http://abc.com/api/v2/…

もちろん、企業向けのイントラサービスでAPIを利用する時もバージョンを入れておいた方が良いでしょう。詳しくは適切なAPIを設計するために注意したいこと「バージョン管理、同期・非同期」 | NTT Communications Developer Portalを参考にしてください。

APIの命名規約など

それを見て動作が想像できるか

APIの命名については、アプリでメソッド名を作るときと同様に考えます。分かりやすいメソッド名は、その後の綺麗なコードを生み出します。

項目名もわかりやすく

これも良くあるパターンがiとかc1などと言った1〜2文字で作成するケースです。queryをqとしたりするのはありかなと思いますが、何に使ってるのか、想像できない項目名はやめた方が良いでしょう。とはいえ、長すぎも厳禁です。長すぎるAPIは見た目も美しくありませんし、定義書を書く時やコーディングする時も面倒でしょう。

命名にあたりAPIでは名詞として複数形を利用するのが一般的になっているようです。

キャメルケースかスネークケースか、はたまたスパイナルケース？

命名についてはいくつかの法則があります。

ケース名 例
キャメルケース userProfile
スネークケース user_profile
スパイナルケース user-profile

これははっきりいって個人の趣味ではないかと思います。

GoogleのSEO対策として、スパイナルケース（ハイフン繋ぎ）だと単語として認識するといわれています。そこが気になるのであれば、スパイナルケースが妥当でしょう。しかしこれが本当であるかははっきりしていません。プログラマの感覚としてはGoogleがスパイナルケースしか対応しないとは考えられません。

もしJavaScriptでの規約に合わせるなら、先頭小文字のキャメルケースが良いでしょう。このように、その時の開発言語に沿って決めてもいいかと思います。

最後に

API設計の導入部分を見ていきましたが、いかがだったでしょうか？最初の設計では多くのものを定義する必要があります。本文中にも記述しましたが、フロントとバックエンド側を繋ぐI/Fを早々に決めておくことが、プロジェクトの並行開発になによりも必要になります。

また、アクセスの考慮やセキュリティの問題など他にも考えるべきポイントは数多くありますが、それは今後紹介していきます。ぜひ参考にしてください！