search
LoginSignup
5

More than 5 years have passed since last update.

posted at

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

  • 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コール
  • HATEOAS (hypermedia as the engine of application state)

  • レスポンス

    • データ構造
      • メタデータは出来るだけHTTPヘッダを利用
      • JSONPではHTTPヘッダ利用できないためレスポンスボディの中にメタデータを格納する必要あり
      • レスポンスに必要なk項目をユーザが選択可能な仕組みもアリ
      • 基本フラット、必要に応じて階層化
      • トップレベルはオブジェクトとする(配列の場合JSONインジェクションの懸念) * フォーマット
      • データ名
        • 少ない単語
        • 連結方法は統一(キャメルケースが一般的)
        • 単数形/複数形を意識する
      • 性別(sex? or gender?)
        • 医療系: 生物学的 sex
        • EC,SNS: 社会的 gender
      • 日付
      • id (巨大な整数)
        • javascriptで扱うと誤差が生じる場合あるので、そのときは文字列として扱う
  • エラー

    • HTTPステータスコードを設定する
    • 詳細情報はボディ?ヘッダ? => ボディが一般的
    • メンテナンス時
      • ステータスコードは 503
      • Retry-After ヘッダでメンテナンス終了予定を示す
    • セキュリティの観点で詳細な情報は返さないケースも考慮する
      • 開発時は詳細返すが本番では返さないというのもあり
  • HTTP仕様

    • ステータスコード
      • 200系
        • POST成功 201
        • 削除成功 204
        • その他成功 200
    • キャッシュ
      • Varyヘッダを設定する

    * CORS

  • 変更しやすいAPI

  • セキュリティ

    • https化
    • 特別なヘッダがついてなければ処理しない
    • Content-Type を正しく設定(application/json)
    • X-Content-Type-Options: nosniff
    • JSONの文字列をエスケープ
    • JSONのトップレベルはオブジェクトにする
    • セッション管理をWebページとは切り離す * ブラウザからの利用を制限するために特定のヘッダの値をチェックする
    • Rate limit の実装(Flaskの場合) http://flask.pocoo.org/snippets/70/

サポートページ

参考リンク

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
What you can do with signing up
5