Siy & Diy

Home | About

Okachi.js - Web API : The Good Parts : 5章 設計変更しやすいWeb APIを作る 輪読会

Web API: The Good Parts

5.1.1 外部に公開しているAPIの場合

  • LSUDs (large set of unknown developer)
    • 外部に広く公開されているWeb API
    • 大変なこと
      • 切り替え
      • 周知

5.1.2 モバイルアプリケーション向けAPIの場合

  • SSKDs (small set of known developer)
    • アップデートしないと古いまま
    • 更新に時間がかかる

5.1.3 ウェブサービス上で使っているAPIの場合

  • ブラウザキャッシュの問題

5.2 APIをバージョンで管理する

  • 一番良いのは、公開したら変更しない
    • 別のエンドポイント
    • 別のパラメータ
    • バージョン番号をふる

5.2.1 URIのバージョンを埋め込む

  • Tumblrの例
  • Twitterの例
  • そのほかの例

5.2.2 バージョン番号をどうつけるか

5.2.3 バージョンをクエリ文字列に入れる

  • パスとクエリの違い
    • 省略可能になる

5.2.4 メディアタイプでバージョンを指定

  • HTTPでは、Content-Typeヘッダ
    • JSONでは、application/json
    • XMLならapplication/xml
  • サブタイプ
  • Varyヘッダ
  • 独自ヘッダ

5.2.5 どの方法を採用するべきか

5.3 バージョンを変える際の指針

  • クライアントのコスト
  • サーバのコスト
  • SDKのメンテナンスコスト

5.3.1 常に最新版を返すエイリアスは必要か

  • 同じ方法でアクセスしても挙動が変化する可能性

5.4 APIの提供を終了する

  • 複数のバージョンを運用し続けるのはコスト
    • セキュリティの対応
    • バックエンドの更新
  • 終了日時のアナウンス

5.4.1 ケーススタディ : Twitterの場合

5.4.2 あらかじめ提供終了時の仕様を盛り込んでおく

  • 410 Goneを返す
  • エラーメッセージで伝える
  • 強制アップデート
  • 後方互換性のある呼び出し

5.4.3 利用規約にサポート期限を明記

  • 利用規約に同意
  • 期間を決める
  • 一度公開したポリシーを変えるのは、時間がかかる

5.5 オーケストレーション層

  • 汎用性のある設計
  • one-size-fits-all (OSFA) アプローチ
  • Client Adapter Code
  • 作成するのは、クライアント側のエンジニア

© 2018 kazuhiro hara.