【API】設計手順

1.機能一覧を書き出す。

例えば、以下のようなもの。

• ユーザー登録
• ユーザー一覧
• ユーザー検索

2.APIとして必要なものを整理する。

例えば、「ユーザー一覧」と「ユーザー検索」のAPIは一つにまとめれるなど。

3.URIを決める。

短くシンプルな物にする。

人間が読んで理解できるものにする。

例えば、aとかbとかの名前になっているURLにはしない。

なお、命名に関しては「ProgrammableWeb」などを見て自分が使っているAPIに近い物の命名を確認すると良い。

大文字と小文字を混在させない。

基本的には小文字のみのURIにするのが普通。

大文字が混ざった場合は、404エラーとして返しているサイトが多い。

データの紐付きがある場合は、階層化する。

例えば、ユーザーの会社情報に対して処理を記述する場合は下記のようなURLになる。

複数の単語をつなぐ必要がある場合はハイフンを利用する。

特に特別なルールはないようですが、一般的に一番採用されているため。特に理由がなければハイフンにする。次点で_（アンダースコア）が良い。

ホスト名

以下のようにホスト名には自社のホスト名の先頭にapiをつけるのが主流です。

4.HTTPメソッドを決める。

メソッド	説明
GET	情報を取得するために使用
POST	新規登録
PUT	更新
DELETE	削除
PATCH	一部更新
HEAD	リソースのメタ情報の取得

5.クエリパラメータを決める

クエリパラメータとパスパラメータの使い分け

パスパラメータはリソースを一意に表すことができる情報の場合に使います。クエリパラメータはリソースの識別に関係ない情報をバックエンドに送る場合に使います。

検索条件の絞り込み

検索条件の絞り込みのために使う検索パラメータはこれを使います。また、ページネーションを実装する際も使います。

取得数

以下のような英単語を使います。

• count
• limit
• per_page

取得位置

以下のような英単語を使います。

• page
• offset

組み合わせは決まっている。

「page/per_page」 or 「offset/limit」と組み合わせパターンはほぼ決まっています。

検索条件項目の命名

複数ある場合はnameやcustomer_idなどと具体的にパラメータ名をつけることが多いですが、検索対象のフィールドが一つに決まっている場合はqとだけする場合もあります。

単一選択項目の表現方法

例えば、ラジオボタンで性別を表す場合はURL上では数値(1,2)よりも文字列(male、femaleなど)で渡すことが一般的のようです。