Skip to content

Instantly share code, notes, and snippets.

@hypermkt

hypermkt/web-api-the-good-parts-reading-memo.md

Last active February 21, 2018 05:39
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save hypermkt/c166917a50a1935ceb4b040fc386ab16 to your computer and use it in GitHub Desktop.
Save hypermkt/c166917a50a1935ceb4b040fc386ab16 to your computer and use it in GitHub Desktop.
Download ZIP
Web API The Good Partsの読書メモ
Raw
web-api-the-good-parts-reading-memo.md

Web API The Good Parts 読書メモ

5章 設計変更をしやすいWeb APIを作る

  • APIをバージョン管理する
    • URIのバージョンを埋め込む
      • URIのパスの一番先頭につけるのが一般的
      • v を先頭につけることでバージョンとはっきり分かる
    • バージョンをクエリ文字列に入れる
      • パスとクエリ文字列の違いは、それが省略可能であること
      • デフォルトでは最新バージョンか下位バージョンはサービス次第
      • クエリ文字列に含めると見た目が冗長になるのでパスのほうが良い
    • メディアタイプでバージョンを指定する
      • メディアタイプとはHTTPではContent-Typeヘッダーを指定する値のこと
        • レスポンスコード、メッセージヘッダ、メディアタイプ一覧表
        • JSONは application/json, XMLはapplication/xml
        • メディア・タイプを使ってバージョンを指定する場合は、クライアントからのリクエストの際にバージョン番号を含むメディアタイプをAcceptヘッダーに入れてサーバー送信をする
          • Accept: application/vnd.example.v2+json
        • サーバー側では要求されたメディア・タイプを元にレスポンスを生成し、それをクライアントに返す。その際にはContent-TypeとVaryヘッダーを返す。（これはめんどいな・・・）
          • Content-Type: application/vnd.example.v2+json
          • Vary: Accept
        • Content-Typeが完全にapplication/jsonと一致していないとJSONと判断してくれないクライアントライブラリもあって独自のメディアタイプをエラーと認識してしまう危険性も有り
    • どの方法を採用するべきか
      • もっとも利用されているのはURIのパスにバージョンを入れる方法
        • URIを見るだけでAPIのバージョンが分かって良い
        • 著名サービスもこの方式
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment