Web API The Good Parts

概要

本

• Web API The Good Parts

かかった時間

• 6 時間

読む前の状態

体系的なAPIのデザイン知識は特になし

読む前後の変化

• APIのリクエストの形式やレスポンスの形式の概要を理解した

• エンドポイント設計の概要を理解した

その他

• OAuth, HTTPの仕様面については読書メモからは省略

WebAPI

WebAPIとは

• WebAPIとは「HTTPプロトコルを利用してネットワーク越しに呼び出すAPI」

• APIはデータを活用するための形式

  • JSON

  • XML

• データの公開は重要

  • サービスを通じてできることすべてを公開する

• 美しいWebAPI

  • 仕様が決まっているものは仕様に従う

  • 使用が存在しないものに関してはデファクトスタンダードに従う

• なぜそのような仕様(デファクトスタンダード)になっているのか

• REST

  • FieldingなRESTアーキテクチャの原則に合わせたウェブサービスシステム

  • PRCスタイルに合わせた簡易なXML(やJSON)＋HTTPインターフェースを採用したシステム

エンドポイントの設計とリクエストの形式

• 公開したAPIがどのように使われるか

  • ユースケースを考える

• WebAPIにおけるエンドポイントとは、APIにアクセスするためのURI

URIの設計

• 覚えやすく、どんな機能を持つURIなのかがひと目でわかる

  • 短く入力しやすい

  • 人間が読んで理解できる

  • 大文字小文字が混在していない

    • 基本はすべて小文字

    • RFC7230上はURIはスキーマとホスト名を除いて、大文字と小文字は区別される

  • 改造しやすい

    • URIを修正して別のURIにするのが容易

  • サーバ側のアーキテクチャが反映されていない

    • URIが反映スべきは機能やデータ構造

  • ルールが統一されている

HTTPメソッド

• 1つのエンドポイントに異なるメソッドでアクセス

  • GET

    • 情報の取得

  • POST

    • 新しい情報を登録

  • PUT

    • サーバ側の情報を変更

    • URIに従属する

  • DELETE

    • リソースの削除

  • PATCH

    • 一部を変更する

APIエンドポイントの設計

• 「あるデータの集合」と「個々のデータ」をエンドポイントとして表現し、エンドポイントに対してHTTPのメソッドで操作を表す

• 注意点

  • 複数形の名詞を利用する

  • 利用する単語に気をつける

  • スペースやエンコードを必要とする文字は使わない

    • パーセントエンコーディングが必要になるため

  • 単語をつなげる必要がある場合はハイフンを利用する

    • 極力単語をつなぎ合わせない

• クエリパラメータとパスの使い分け

  • 一意なリソースの場合は、パス

  • 省略可能な場合はクエリパラメータ

認証

• OAuth

  • 標準化された、広く認知された仕組み

  • 第三者におけるAPIにおいて認可を行うために用いられる

  • サービスを利用する際に、パスワードを入力する必要がない

  • アクセストークンを用いる

• 1.0と2.0

  • 2.0はRFC6749

レスポンスデータの設計

• プログラムが処理しやすいもの

• データフォーマット

  • JSON

  • 指定方法

    • クエリパラメータ

    • 拡張子

    • クリエスとヘッダでメディアタイプを指定

      • Acceptというメディアタイプを指定するHTTPヘッダ

  • JSONP

    • JSONをJavaScriptでラップしたもの

    • CORS制約の対象外

• データ構造

  • APIのアクセス回数をなるべくへらすようにする

  • 送受信されるデータのサイズはなるべく小さく

    • 取得素r項目を選択可能にする

• JSONスタイルガイド(google)

  • https://google.github.io/styleguide/jsoncstyleguide.xml
• 規約など

  • 日付フォーマット(RFC822, RFC850, ANSI C)

• エラーの表現

  • ステータスコード

  • エラーの詳細をレスポンスヘッダorレスポンスボディに含める

    • 実際にはレスポンスボディが大半

    • エラーコード、詳細へのリンク

変更しやすいWebAPI

• 用途によって異なる

  • 外部公開

  • モバイルアプリ向け

  • Webサービス向け

• バージョン管理

  • URIにバージョンを埋め込む

    • http://localhost/v1/ など
    • パスの先頭につけるのが一般的

    • クエリパラメータに埋め込む方法もある

    • セマンティックバージョニング

      • URIに含めるのはメジャーバージョンまでを推奨

  • 後方互換性を保つことが難しい場合のみバージョンアップする

    • セキュリティや権限のルール変更など

Webのセキュリティ

• WebAPIを安全にする

• リスクを理解して、対策を講じる

• セキュリティ問題の種類

  • サーバとクライアントの間での情報の不正入手

    • セッションハイジャック

  • サーバの脆弱性による情報の不正入手や改ざん

  • ブラウザからのアクセスを想定しているAPIにおける問題

  • HTTP通信を暗号化する(HTTPS)

    • Man In The Middle

• ブラウザ

  • XSS(クロスサイトスクリプティング)

    • ユーザから送られてきたJavaScriptが実行される

      • Content-Typeにapplication/jsonを返す

      • X-Content-Type-Option: nosniffを付与する

  • XSRF(クロスサイトリクエストフォージェリ)

    • サイトをまたいで偽造のリクエストを送ることでユーザが意図していない処理を行う

      • GETメソッドをサーバ側に影響を与えるリクエストに使わない

      • XSRFトークンを用いる

      • クライアントから特別なリクエストヘッダを付与してもらう

  • JSONハイジャック

    • APIからJSONで送られてくる情報を悪意ある第三者が盗み見ること

      • <SCRIPT>要素にはCORSポリシーが適用されないため

        • JSONを<SCRIPT>要素で読み取れないようにする

        • JSONをブラウザから必ずJSONと認識するようにする

        • JSONはJavaScriptとしては解釈不可能、実行時にデータを読み込めないようにする

• 悪意あるクライアント

  • パラメータの改ざん

    • 本来アクセスできない情報はサーバ側でチェックして、アクセスを禁止にする

    • クライアントから送信された情報を信頼せずに、サーバ側でも整合性をチェックする

  • リクエストの再送信

    • 繰り返しのアクセスかどうか判断し、問題が生じる場合はエラーにする

• 大量アクセス

  • レートリミット

セキュリティ関係のHTTPヘッダ

• X-Content-Type-Options

• X-XSS-Protection

• X-Frame-Options

• Content-Security-Policy

• Strict-Transport-Security

• Public-Key-Pins

• Set-Cookie