Web API the Good Parts2章

Dec 22nd, 2014

前置き

近況

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

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

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

そういう訳なので

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

「Web API The Good Parts」

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

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

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

エンドポイント設計

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

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)

{
  "error": "invalid_token"
}

7に関して

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

まとめ

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

Good

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