Web API The Good Partsのまとめ Part3

前回の検索とクエリパラメータの設計が途中だったのでもう一度そこの最初から

検索とクエリパラメータの設計

• データ一覧を取得するエンドポイントに絞り込みをかけて検索させる
  • 絞り込みするのに必要なのがクエリパラメータ
• クエリパラメータの取得数と取得位置
  • page/per_pageやlimit/offsetなどが一般的
  • limit/offsetの方が自由度が高い
    • これらは取得位置を相対的に指定するものだが、これには
      1. データ量が増えれば増えるほど時間がかかる
      2. 更新頻度の高いデータの場合、データの不整合が起こりうる
         という問題点がある。
    • 絶対位置で取得することもある
      • 指定したID/日時よりも前
  • クエリパラメータでqをパラメータとして使う場合、全文検索・部分一致を許容することが多い。
    • qであらゆるパラメータの値から部分一致も含めて検索する
  • クエリパラメータとパスの使い分け
    • 一意なリソースを表すのに必要な情報かどうか
    • 省略可能かどうか

ログインとOAuth

• OAuthとは、別のサービスAで登録している情報を利用するために、ユーザーがトークンを利用してサービスBでサービスAの情報を利用できるようにする認証システムのこと。

  • 例えばBasic認証などの場合(Resource Owner Password Credentials)のリクエスト

    POST /v1/oauth2/token HTTP/1.1
    Host: api.example.com
    Authorization: Basic houawreIYfaw48HAF
    Content-Type: application/x-www-form-urlencodeded
    
    grant_type=password&username=mosnipe&password=abc&scope=api
    

    • APIのパスやエンドポイント

      • OAuthは現在バージョンが2.0のためoauth2などとしている
      • エンドポイントはtokenやaccess_tokenなどが一般的
      • Authorizationヘッダはアクセスするサービスが何か？やクライアントアプリケーションが何かを特定するための情報。
        →アプリケーションごとにAPIのアクセス数を制限する場合などに利用する
        →許可していないアプリケーションをブロックする場合などに利用する
        • リクエストボディにclient_id/client_secretという名前で入れることも可能

      HTTP/1.1 200 OK
      Content-Type: application/json
      Catch-Control: no-store
      Pragma: no-cache
      
      {
      "access_token": "vak77K39nkalak",
      "token_type": "bearer",
      "expires_in": 2629743,
      "refresh_token": "kagahka38Ijg30Kr",
      }
      

      • bearerはOAuth2.0用のトークン形式
      • expires_inはアクセストークンの有効期限
      • refresh_tokenはトークンが有効期限切れの際に再発行してもらうために使用するトークン
      • アクセストークン発行後はユーザネームやパスワードを利用する必要はない

HATEOAS

…Hypermedia as the engine of application state

• API設計の別の手法
• 返すデータにURIを含み、次に行う行動や取得するデータが分かるように設計すること。
• この設計では、Content-Typeヘッダにどんなデータ形式かを詳細に記す
  • 通常は
    • JSON→application/json
    • XML→application/xml
  • HATEOASでは
    • application/vnd.companyname.user.detail.vi+jsonのようになる。
• メリット
  • クライアントがURIを知る必要がないので、変更しやすい
    • URIを簡潔にしなくて良い
    • APIにおけるURIの間違いによるバグを減らすことができる。
• まだこの設計を導入するのは時期尚早

まとめ

1. 覚えやすく、どんな機能を持つかがひと目でわかるエンドポイントにする
2. 適切なHTTPメソッドを利用する
3. 適切な英単語を利用し、単数形、複数形にも注意する
4. 認証にはOAuth2.0を使う

感想

• 検索の仕様や実装をまだ知らないけど、基本はデータ一覧を取得するエンドポイントに絞り込みをかける方法なのだろうか？
• OAuthはトークンの概念があまり分かっていないころInstagramのAPIを使ってデータ取得をしようとして何度もinvalid tokenのエラーを返されていた記憶があります。
• HATEOASは初めて知った概念ですが、APIでURIを取ってくるって理解をしてます。なんとなくセキュリティ上怖い感覚があります。杞憂か…