Open8日前にコメント追加1

API設計

bz0

API設計の方針としてコンシューマ視点を重視（ユーザが何ができるかに焦点を合わせる）
- 内部構造に合わせてユーザが不便を強いられるのはよいシステムとは言えない
- 最適解でなくともユーザが慣れている方法に合わせるべき
- APIは基本的にソフトウェアの操作パネル、身近にあるIFと同じル402 Payment Requiredールに従うべき
- APIのことをわざわざ考えることなく理解しやすく使いやすいこと
APIの設計
- 必要な情報
  - 利用者は誰か
  - 何ができるか
  - どのように行うか
  - 何が必要か
  - 何が返されるか
  - 入力はどこから得られる？
  - 出力はどのように使われる？
- プロバイダの視点に立って設計してないか？
  - データモデルの露出はプロバイダ視点の最も顕著な例
  - データをどのように操作するのかまでAPIから分かってしまうことがあるのも問題
- HTTPステータスコード：リクエスト処理の結果
- リソースのパス：リソースの関係と種類が明らかになるようにする
  - パスの要件は一意であること
  - エンドポイントの名前は複数形であるべき
    - https://qiita.com/ryo88c/items/0a3c7861015861026e00
  - 特定の事象を示すエンドポイントを作るべきではない
    - URI が示している事以外の暗黙的な知識を必要としない表記とすべき
  - リソースを表現するため、何に対して処理を行うかを明示すること
  - パスパラメータ（/categories/1）で処理対象を指定
- HTTPメソッド：アクション（何をさせるのか）
  - GET：取得
  - POST：作成
  - PUT：置換
  - PATCH：変更、部分的な更新
  - DELETE:削除
- プロパティ：名前、型、必須か、説明
- 単純な入力、情報価値のあるフィードバックが原則
  - エラーは明確に問題が何なのかを伝える
  - 何が完了したか、次のステップに役立つ情報を提供する
- 複数のエラーをひとつずつ報告するのは避ける
  - 全てを一度に返す
- コンテントネゴシエーション(HTTPヘッダ)：データフォーマットと言語を指定等
  - 同じURIにおけるさまざまな表現のリソースを提供するために使用する仕組み
  - https://developer.mozilla.org/ja/docs/Web/HTTP/Content_negotiation
- ページング
  - クエリパラメータ：page,pageSize
  - HTTP ヘッダ：Range: items=0-9
- レスポンスのメタデータ
  - ページングに関するデータ等
    - 現在のページ数、全ページ数
    - 今どこにいて何ができるかを示す
- 関係性の整理
  - 階層構造によりグループ化する
  - 重要度が高いものを上に低いものを下に
  - データの細かさにはプロパティの数と深さがある
- セキュリティ
  - クレデンシャル（Credential）：認証に使用される情報全般
  - 認証問題なければアクセストークンが発行され、それが認証済みであることを証明する
  - リソースとアクションに基づいてスコープを定義
    - コンシューマが必要なゴールにのみアクセスできるようにする
  - エラーフィードバックにも、情報漏えいしないように不要な情報を渡さないようにする
  - APIのベースとなっている技術スタックに関する詳細情報が実装によって提供されることがあってはならない
- API呼び出し回数が多いと起きる問題
  - アプリが遅い、バッテリーを食いすぎる、データ通信を使いすぎる
  - クラウドプロバイダの高額な請求金額
- 遅延、レイテンシ：呼び出しが多いとレイテンシが膨れ上がるので時間かかる
  - サーバへの接続、低レベルネットワーク通信の開始、暗号化等の様々なアクション
  - レイテンシ＝データ転送のリクエストが実際に処理されるまでの時間的遅延を表す指標
- ネットワーク通信の最適化
  - HTTPベースでは圧縮の有効化と持続的接続
  - キャッシュの有効化と条件付きリクエストで呼び出し回数を減らす
  - HTTP/2の利用
    - 効率のよい持続的接続、同時リクエスト、バイナリトランスポートを最初からサポート
    - 圧縮の有効化＋持続的接続とほぼおなじ効果
HTTPステータス
- 200 OK：最も一般的、単にOKという意味だったり更新・削除が完了した際等
- 201 Created：新規作成の場合
- 202 Accepted：バッチ処理が受け入れられた場合
- 207：複数のリソースに関する情報を一度に返すとき
  - https://www.rfc-editor.org/rfc/rfc4918#section-13
- 4xx：システム側で正常なエラー処理として判断されるもの
  - 400 Bad Request：必須パラメータが指定されてない
  - 401 Unauthorized：クレデンシャルが不明または無効
  - 402 Payment Required：決済情報が必要であったり、課金上限を超えてしまった場合
  - 403 Forbidden：パーミッションが無効
  - 404 Not Found：リソースが不明（パスパラメータが正しくない）
  - 405 Method Not Allowed：許可されていないHTTPメソッドを利用した場合
  - 406 Not Acceptable：リクエストヘッダ情報が間違っていた場合
    - mime、シグネチャが間違っている、セットすべきヘッダーがない
- 5xx：
  - 503 Service Unavailable
    - サーバーがリクエストを処理する準備ができていないことを示す
    - 一時的なエラー