Upgrade to Pro — share decks privately, control downloads, hide ads and more …

おさらいWebAPI

 おさらいWebAPI

WebAPIの設計におけるベストプラクティスやRESTとの関係についてまとめて発表した社内勉強会用の資料です

- RESTとは
- エンドポイントのプラクティス
- リクエストヘッダのプラクティス
- ステータスラインのプラクティス
- レスポンスヘッダのプラクティス
- レスポンスボディのプラクティス

Yuta Fujii

March 19, 2021
Tweet

More Decks by Yuta Fujii

Other Decks in Programming

Transcript

  1. Yuta Fujii 本資料を作るにあたり参考にしたリソース • Representational State Transfer (REST), Roy Fielding,

    2000 • Richardson Maturity Model • REST Resource Naming Guide • HTTP RFC2616 • RESTとRESTfulとRESTishについて • Web API: The Good Parts
  2. Yuta Fujii RESTって RESTであるための6つの制約 1. クライアント・サーバー構成(Client-server architecture) 2. ステートレス(Stateless) 3.

    キャッシュ可能(Cachability) 4. 単一インターフェイス(Uniform Interface) 5. レイヤードシステム(Layered System) 6. コードオンデマンド(Code-on-demand)
  3. Yuta Fujii REST levelという成熟度モデルの導入(2010,Richardson, Martin) Level 0  XMLでやりとり(The Swamp of

    POX) Level 1  リソースの導入(Resources) Level 2  なるべく正しいHTTP verbを使う (HTTP verb) Level 3  リソース制御の抽象化(Hypermedia Controls) Level 3まで満たして RESTful RESTって
  4. Yuta Fujii REST level Level 0  XMLでやりとり(The Swamp of POX)

    Level 1  リソースの導入(Resources) Level 2  なるべく正しいHTTP verbを使う (HTTP verb) Level 3  リソース制御の抽象化(Hypermedia Controls)←これがしんどい RESTfulは大変
  5. Yuta Fujii エンドポイント URI基本編 - Consistency is the key •

    短く入力しやすい • 人間が読んで理解できる • 大文字小文字が混在していない • 改造しやすい • _ ではなく - を使う • バージョンを含んでOK
  6. Yuta Fujii エンドポイント|HTTP verb RESTful編 • 適切なHTTP verbを用いる(Level 2) Best

    Practice編 • 適切なHTTP verbを用いる ◦ XSRF対策 • メソッドオーバーライド ◦ X-HTTP-Method-Overrideヘッダ ◦ _methodパラーメータ
  7. Yuta Fujii RESTful編 • Cache-Controlヘッダは入れる(Cachability) • Content-Typeヘッダは入れる ◦ トップレベルはapplications/ が主流

    ◦ 独自タイプは “application/x-mytype” “x-”で始めるのは古い.ドットで繋ぐ( application/vnd.companyname.awesomeformat ) レスポンス|response header
  8. Yuta Fujii レスポンス|response header Best Practice編 • Content-Typeヘッダは入れる • X-Content-Type-Options:

    nosniff • 独自のヘッダは “x-”接頭辞 ◦ 必ずつける必要はない
  9. Yuta Fujii レスポンス|response body Best Practice編 • エンベロープは冗長なので避ける ◦ メタ情報はHeader

    • 配列返却のときも最上位はオブジェクトで返す ◦ JSONインジェクションリスクを回避できる • エラーはステータスコードで表現する ◦ 詳細はbodyで記述する ◦ 実際にはエラーも200OKで返るAPIも...