API設計において気を付けること
仕事でWeb-APIを設計することになりそうなので、個人的によく見そうなことをまとめます。
APIで気を付けること-1
サイトの内容を簡潔に書いてすぐに見返せるようにしてます。
1. 同じ事柄を表すリソース構造には一貫性があること
叩くAPIによって、リソースの構造が異なってはいけない。
2. 表示を意識したパラメータ・データ構造を避けること
例：表示とデータの違い 「10」が扱うデータであり、「0010」は表示を含んだ情報
3. クライアントがハンドリングしそうな値は文字列ではなく数値を使う
「/」を使ってみたり、finalみたいな文字列だったりは使わない
4. 1つの属性が複数の値をもつことを考慮する
複数の値を持つのかしっかり確認し、配列構造にしておく
5. 多数の属性の値を組み合せて利用するような値は設定しない
送信する値は独立性を保たせ、組み合わせて利用するような状態にしない
6. コレクションリソース（一覧の意）を返すときは、数の増加を想定しページングを設ける
トップレベルで配列を返すよりも、１段ネストさせたほうが融通がきく。
7. ページングをする際のデフォルトの動きは、データを出来る限り全て返せるように振る舞う
一覧取得の際は、クライアントにクライアントの選択で自由に値を返すようにしてあげる
8. 転送する通信帯域（データサイズ）が問題になりそうな場合、返すパラメータを絞れるクエリを検討する
ページングをデータ削減のために用意するのではなく、
データ削減には返すパラメータで少なくして改善する。
9. 領域（ドメイン？）概念の異なる値を同じ配列に入れない。別パラメータとして設ける。
しっかりジャンルごとに分けた内容を送るようにする
結構当たり前にも感じるような内容も多かったが故に実際に作成するときには必ず確認したい。 参考ページ
APIで気を付けること-2
URL設計
- 小文字のみを使用する。
- 単語をつなげる必要がある場合はダッシュを利用する。
- 単数形よりも複数形をつかう。
- スペルミスをしない。
- URLの階層は浅く保ち、複雑さはクエリパラメーターに押しこむ。
- クエリパラメータ名は配列で複数渡すものについては複数形、一つだけ渡すものについては単数形とする。
- ページングにはper_page、pageというパラメータ名を使用する。
レスポンス
- レスポンスデータフォーマットはJSONのみを原則とする。
- データ名の単数形/複数形に気をつける。
- 単語の連結にはキャメルケース（userIdなど）を用いる。
JSON がベースとしている JavaScript の命名規約において、キャメルケースの利用がルール付けされているケースが多いため。 - 日付データの形式にはRFC 3339を用いる。また、時差対応しやすくするため、UTCで返すことを原則とする。
エラー
- リソースが見つからない場合JSON形式で、Httpステータスを返却する。
API設計に役立ちそうなAPI
ここにおいてある
