1.機能一覧を書き出す。
例えば、以下のようなもの。
- ユーザー登録
- ユーザー一覧
- ユーザー検索
2.APIとして必要なものを整理する。
例えば、「ユーザー一覧」と「ユーザー検索」のAPIは一つにまとめれるなど。
3.URIを決める。
短くシンプルな物にする。
人間が読んで理解できるものにする。
例えば、aとかbとかの名前になっているURLにはしない。
なお、命名に関しては「ProgrammableWeb」などを見て自分が使っているAPIに近い物の命名を確認すると良い。
大文字と小文字を混在させない。
基本的には小文字のみのURIにするのが普通。
大文字が混ざった場合は、404エラーとして返しているサイトが多い。
データの紐付きがある場合は、階層化する。
例えば、ユーザーの会社情報に対して処理を記述する場合は下記のようなURLになる。
1 |
http://localhost/v1/users/:id/companies/:id |
複数の単語をつなぐ必要がある場合はハイフンを利用する。
特に特別なルールはないようですが、一般的に一番採用されているため。特に理由がなければハイフンにする。次点で_(アンダースコア)が良い。
ホスト名
以下のようにホスト名には自社のホスト名の先頭にapiをつけるのが主流です。
1 |
https://api.twitter.com |
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など)で渡すことが一般的のようです。
この記事へのコメントはありません。