More than 5 years have passed since last update.

【読書メモ】Web API: The Good Parts

読書メモ

Posted at 2017-03-07

Web API を公開する
Web API を美しく設計する（ただしRESTにこだわりすぎない）
URIの設計
- 短く入力しやすい
- 人間が読んで理解できる
  - 一般的な英単語を使う → ProgrammableWeb のAPIディレクトリが参考になる
- 大文字小文字が混在していない
- 改造しやすい
- サーバ側のアーキテクチャが反映されていない
- ルールが統一されている
URIがリソース、メソッドが操作
リソースは複数形の名詞を使う
クエリパラメータとパスの使い分け
- 一意なリソースを表す情報 → パスに含めるのが適切
- 省略可能な情報 → クエリパラメータ
SSKDs (Small Set of Known Developers) : 少数の既知の開発者
LSUDs (Large Set of Unknown Developers) : 大多数の未知の開発者
1ページ 1APIコール / 1セーブ1APIコール
- 速度 = UXを優先
- 表示や保存するデータの整合性の保証
- https://www.youtube.com/watch?v=8BsrAblL23U
  - 2016 http://boston2016.apistrat.com/
- オーケストレーション層
HATEOAS (hypermedia as the engine of application state)
- APIのレスポンスの中に次のアクションを呼び出すAPIのURLが埋め込まれている
- REST Level3
- https://www.slideshare.net/philharveyx/http-caching-ftw-rest-fest-2013
- アプリケーションは先頭ページのAPIのURLだけをハードコードすれば良い
レスポンス
- データ構造
  - メタデータは出来るだけHTTPヘッダを利用
  - JSONPではHTTPヘッダ利用できないためレスポンスボディの中にメタデータを格納する必要あり
  - レスポンスに必要なk項目をユーザが選択可能な仕組みもアリ
  - 基本フラット、必要に応じて階層化
  - トップレベルはオブジェクトとする（配列の場合JSONインジェクションの懸念）
    * フォーマット
  - データ名
    - 少ない単語
    - 連結方法は統一（キャメルケースが一般的）
    - 単数形/複数形を意識する
  - 性別(sex? or gender?)
    - 医療系: 生物学的 sex
    - EC,SNS: 社会的 gender
  - 日付
    - RFC 3339 を推奨 (RFC 3339の日付形式)
    - TimeZoneはUTCを推奨
    - HTTPヘッダの場合は RFC822 に従う
  - id (巨大な整数)
    - javascriptで扱うと誤差が生じる場合あるので、そのときは文字列として扱う
エラー
- HTTPステータスコードを設定する
- 詳細情報はボディ?ヘッダ? => ボディが一般的
- メンテナンス時
  - ステータスコードは 503
  - Retry-After ヘッダでメンテナンス終了予定を示す
- セキュリティの観点で詳細な情報は返さないケースも考慮する
  - 開発時は詳細返すが本番では返さないというのもあり
HTTP仕様
- ステータスコード
  - 200系
    - POST成功 201
    - 削除成功 204
    - その他成功 200
- キャッシュ
  - Varyヘッダを設定する
* CORS
変更しやすいAPI
- バージョン管理
  - Semantic Versioning http://semver.org/
  - メジャーバージョンのみURIに含める（滅多に上がらない）
  - できる限り後方互換を残す方法（マイナーバージョンアップ）で対応
  - エイリアスは不要(バージョンは明示的に指定される方が良い）
- 廃止
  - Blackout test
  - HTTP status 410 (Gone)
- オーケストレーション層
  - OSFA (One size fits all) = 最大公約数的 : サイズが大きく無駄になる
  - The future of API design: The orchestration layer
  - クライアントアダプタ: The Netflix Tech Blog: Embracing the Differences : Inside the Netflix API Redesign
  - AWS であれば API Gateway で実現できる？
セキュリティ
- https化
- 特別なヘッダがついてなければ処理しない
- Content-Type を正しく設定(application/json)
- X-Content-Type-Options: nosniff
- JSONの文字列をエスケープ
- JSONのトップレベルはオブジェクトにする
- セッション管理をWebページとは切り離す
  * ブラウザからの利用を制限するために特定のヘッダの値をチェックする
- Rate limit の実装(Flaskの場合) http://flask.pocoo.org/snippets/70/

サポートページ

http://takaaki.info/web-api-the-good-parts/

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up