Web API the Good Parts2章

前置き

近況


ざっくりと書くと、お前エンジニアなのに勉強しなくていいの?という状態

  1. 免許が取れたので単車を乗り回している(運転が楽しくて毎日、運転しているような)
  2. 昨年よりも比較的、仲がいい友人(男女問わず)と遊ぶ機会が多くなったかも…
  3. 気の合う仲間と組んで、(Swiftで)アプリ作っている
  4. その気の合う仲間への技術指導していたり…

なんだか、教えることが多くなって自分が学習している時間が比較的減ってきているそんな感じががが

そういう訳なので


本屋でざっくりと見かけてツボに嵌った本を読んでいこうかと

「Web API The Good Parts」

なのですが、上記3,4が結構あるので中々進まないという(ぉぃ

ということなので、なるたけ気になるところ(覚えておくべきところ)だけまとめていこうかなと

斜め読みした感じでは、結構ツボに嵌る内容なので自分のバイブルに入選してもいいかなと思ってたり。

エンドポイント設計

  1. 公開する機能を先に設計する
  2. 覚えやすく、どんな機能を持つURIかひと目で分かるようにする
  3. HTTPメソッドの活用
  4. 設計の注意点
  5. クエリパラメータ
  6. ログインや認証
  7. ホスト名とエンドポイント

1に関して


どんなAPIが必要かどうかを先に洗い出しておく

2に関して


  • 短く入力しやすいURI
  • 人間が読んで理解できるURI
  • 大文字、小文字が混在しないURI
  • 改造しやすいURI
  • サーバ側アーキテクチャが反映されていないURI
  • ルールが統一されたURI

3に関して


HTTPメソッドを有効活用

  • Restfulな形で活用すれば、一般的な形

4に関して


  • 複数形の名詞を利用する
  • 利用する単語に気をつける((ProgramableWeb)[http://www.programmableweb.com/]等、他のサービスを参考に)
  • スペースやエンコードが必要な文字は避ける
  • 単語をつなげる場合はハイフンにする(SEO的に有利なことも)

5に関して


  • 相対位置を使用する場合、データ数が多くなると取得件数が減ること、更新頻度が高いものは不整合が起きやすくなることに注意
  • 絶対位置を使用する場合、クエリパラメータが「x以降」,「この日付よりも古いもの」という形でクエリパラメータをもたせたほうがよい
  • 日付の形式は、RFC3339に規定されている「1970-01-01T00:00:00Z」の形にする
  • 絞り込みのパラメータは、「q」のような形は曖昧検索に取られやすいので完全一致の場合は適切なパラメータにすること
  • 一意なリソースを表すのに必要な情報: パス
  • 省略可能: クエリパラメータ

6に関して


  • OAuthを使用して、標準的な形にする

標準的なOAuthに則るとエラーメッセージ(RFC6749, RFC6750)は、以下のような形式となる (当然ながらhttpステータスは401)

1
2
3
{
  "error": "invalid_token"
}

7に関して


  • ホスト名にapiを入れるのが主流
  • 企業で複数のサービスをホストする場合、例外的なホスト名
  • サービスとしてのapiの場合はホスト名にapiをいれたほうがよい(外部から使われるため)
  • プラットフォームの場合、service等をホスト名にいれる

まとめ


  • 一般的なURI設計がそのまま適用できる
  • APIならではのルール、デファクトスタンダードがある
  • URIはリソースを表すものなので、URIとHTTPメソッドの組み合わせで処理の対象と内容を設計をする

Good

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