Open15

WebAPIの開発・設計・実装・運用

設計
rest
REST API
Web API
api設計
koukou

RESTとは設計のガイドライン

RESTの制約

  • クライアントサーバー
  • スタートレス
  • 統一インターフェース
  • キャッシュ
  • 階層化システム
  • コードオンデマンド
koukou

クライアントサーバー

関心の分離をすること

koukou

スタートレス

リクエストは必要なすべての情報を含んでいる
状態を持たないこと

サーバーのスケールがしやすい

koukou

統一インターフェース

ルールを統一して異なるアーキテクチャ間の通信を簡単にする

koukou

リソース指向

以下のgithubのエンドポイントのようにURLからリソースが何かわかること

/repos/{owner}/{repo}/branches

koukou

以下を見ていく、楽しそう

  • エンドポイント設計
  • クエリパラメーター設計
  • リクエストレスポンス設計
koukou

エンドポイント設計

よくあるNG

Idが連なると可読性が悪化する
（/categories/123/543）

❌ /categories/{categoryId}/{productId}
↓
✅ /categories/{categoryId}/products/{productId}
or
✅ /products/{productId}

その他の注意点

  • 英語の小文字だけ使う
  • 日本語は使わない
  • 複数単語はハイフンで繋ぐのが無難
koukou

リクエストレスポンスのデータ設計

入れすぎない塩梅を教えて欲しい

一つのレスポンスデータに全部の情報を入れすぎない

どこのページで使われてどのくらいの情報が必要か見る感じ？
クエリパラメーターでリミット使ったりする。

レスポンスデータが大きいとサーバー側の処理が重くなる。JOINなど不要な結合処理が発生する

koukou

WebAPIの日付情報の扱い

知らなかった

日付情報をどういうフォーマットで扱うかは悩ましい問題であることがしばしば

どんなフォーマットがある？

フォーマット

  • RFC 3339（最も一般的に使われるフォーマット）
  • Unix Timestamp
  • RFC 2822
    ※米RFCは国際規格のこと

Unix Timestampでは100日後、みたいな計算が楽
RFC 3339ではうるう年の考慮して計算しなきゃいけない

koukou

ステータスコード設計

200,300,400
MDNのHTTPレスポンスステータスコードを見ろ！

200のように末尾00よりも201,301など具体的な内容を返すようにするのが基本。

koukou

300番台

ほう

クライアントから見た301と302ではキャッシュ周りの違いがある

301が帰ってくるとクライアントはキャッシュをする。変更前のURLにアクセスせず、変更後の新しいURLを覚えておく。

302は一時的な変更のため、前回と同じURLに再度リクエストを送る。

キャッシュコントロールというレスポンスヘッダーでキャッシュ期間をサーバーが指定できる。

サーバーが指定しない場合はクライアントのブラウザに依存する。

Chromeは結構長い期間キャッシュを保持するみたい

※レスポンスヘッダーのLocationにリダイレクトのURLが入ってる

koukou

400番台

紛らわしいww

401 Unauthorized は"Unauthorized"(不許可)とされているが"unauthenticated"(未認証)のことです。

403 Forbiddenが認証されてるが不認可の時に返すエラーコード。

koukou

500番台

ロードバランサーやるやん

503 Service un available サーバーがダウンして処理ができないときに返ってくる
サーバーが落ちてるのでロードバランサーがこれを返してくれる

koukou

エラーの情報をどうやって伝えるか

  • 適切なステータスコードを使う
  • レスポンスデータに含める

よく見るレスポンスデータ

{
  "errorCode": "auth-001",
  "message": "Road operation is not allowed.",
  "help": "https:example.cod/help/error/auth-001"
}

RFC 9457規格

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough access.",
  "status": 403,
  "detail": "This action is only allowed to admin users",
  "instance": "/users"
}

"type"：エラーを表すURI、詳細なドキュメントが見られる
"instance": 問題発生のリソース

koukou

WEB APIとキャッシュ

確かに〜！！

何を持って「同じリクエスト」なのか？

  • GETメソッドである
  • URLが完全に一致する
  • Varyで指定したヘッダー内容が一致する

そうなんだ

リクエストヘッダーの値は一致してるかはキャッシュ時に考慮しない

Vary:レスポンスヘッダーにつける値。キャッシュを使い回すかの判断に指定した項目のヘッダーを見るようにする