読者です 読者をやめる 読者になる 読者になる

Web API The Good Parts 1~2章の自分的まとめ

自分は本を読むのが遅いほうだが、最近は読んだ後に自分の中にあまり内容が残らないことが多くなってきた。。。
なので、これからは読んだ本があれば、随時自分の中でまとめたことをアウトプットとしてまとめていきたい。

今回、読んでいる本はこちら!

Web API: The Good Parts

Web API: The Good Parts

1. Web API とは何か

1.1 WEB API の重要性

まあつまりAPIを開発していたら公開したほうがよいということ。
利用者がサービスに付加価値を与えてくれ、コアとなるサービスがより発展するから。

ほんとにその通り。
ただここでは触れていないが、公開するならセキュリティとか気になるところ…
6章で紹介されるので一旦、おあずけw

1.3 何をAPI で公開すべきか

サービスのコアの価値のある部分をすべて利用可能なように公開すべき。
そこに価値があるため。

公開したAPIの運用の方法はいくつかある。
多くはレートリミット、つまりアクセス数の制限を設けている。
それ以上のアクセスがあれば有料とするなどの運用もあり。
レートリミットについても6章で紹介されるので一旦、おあずけw

API を公開することで、優先順位をさげていた機能や全く思いつきもしなかった新しい機能を誰かが作ってくれるかもしれないという効果がある。
このように、(直接サービスを使うのではなく、)API を提供し、それを複数組み合わせたアプリケーションがユーザにサービスを行う”間接販売”モデルになっていく。

1.4 Web API を美しく設計する重要性

設計の美しいWeb API

  • 使いやすい
  • 変更しやすい
  • 頑強である
  • 恥ずかしくない

当たり前だけど超重要!
この章はしっかり読んだ置いたほうがよい!

1.5 Web API を美しくするには

そのためには

デファクトスタンダードを決める際に参考になるサイトはProgrammableWeb。

http://www.programmableweb.com/

(世界中のAPI が集められているサイト。
なんかアプリ作ろうとしたらここからAPI を選定するといいかも)

1.7 対象となる開発者の数とAPI の設計思想

  • LSUDs(large set of unkown developers)
    対象が不特定多数のため、さまざまなユースケースを想定して汎用的にすべき。
  • SSKDs(small set of kown developers)
    特定の開発者にとって便利で使いやすくすべき。

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

2.2 API エンドポイントの考え方

覚えやすく、どんな機能をもつURI なのかが一目でわかるのがよい。
そのためには

  • 短く入力しやすいURI
  • 人間が読んで理解できるURI
    • むやみに省略しない
    • 正しい英語を使う
  • 大文字小文字が混在していないURI
  • 改造しやすいURI
  • サーバ側のアーキテクチャが反映されていないURI
  • ルールが統一されたURI

自分の情報のエイリアス

idではなく、me, self を使う。

2.3 HTTP メソッドとエンドポイント

正しくHTTPメソッドを使いましょう!

メソッド 用途
GET 情報の取得
POST 情報の登録
PUT 情報の(全体)更新
DELETE 削除
PATCH 情報の一部更新

get,postメソッドしか使えない環境のために、X-Http-Method-Override を使えるようにしておくべき。

2.4 API のエンドポイント設計

リソースをURIにする。

ex.ユーザ情報

 https://api.example.com/v1/users
 https://api.example.com/v1/users/:id

それ以外の注意点。

  • 複数形の名詞を利用する
  • 利用する単語に気をつける
  • スペースやエンコードを必要とする文字を使わない
  • 単語をつなげる必要がある場合はハイフンを利用する

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

クエリパラメータで絞込みをする。

 https://api.example.com/v1/users?name=ken

クエリパラメータとパスの使い分けは以下の2観点。

  • 一意なリソースを表すのに必要な情報かどうか
  • 省略可能かどうか

ページネーションはper_page/page or limit/offsetのいずれかを推奨。
page は1始まり、offsetは0始まり。

2.6 ログインとOAuth2.0

OAuth は認可を行う。
例えばFacebook の情報を自サービスで使う場合、以下の図のようにトークンのやり取りを行い、認可をもらう。
重要なのはconsumers(ここでは自サービス)ではログイン情報(ID,パスワード)は持たず、
ユーザはservice Providers(ここではFacebook)にログインするだけでよく、
その際にconsumers にどのような権限を与えるか制御できる。

f:id:AHA_oretama:20160627013911j:plain

自サービスでログインを行う場合、OAuth2.0 のGrant Type=Resource Owner Password Credentials で実装する。

参考

Grant Type 用途
Authorization Code サーバサイドで多くの処理を行うウェブアプリケーション向け
Implicit クライアントサイドで多くの処理を行うアプリケーション向け
Resource Owner Password Credentials consumers を利用しないアプリケーション向け
Client Credentials ユーザ単位での認可を行わないアプリケーション向け

ここら辺は実際に実装してみないとよくわからない。

2.9 HATEOAS とREST LEVEL3 API

HATEOAS
hypermedia as the engine of application state
API の返すデータの中に、次に行う行動、取得するデータなどのURI をリンクとして含めること。

REST LEVEL3 API
HATEOAS の概念の導入。
LEVEL0~2はそれぞれHTTP、リソース、メソッドの導入。

Spring でもプロジェクトがあるので、使ってみるといいかもしれない。
http://projects.spring.io/spring-hateoas/

ここまでの所感

API 設計の基礎の基礎となる部分であり、
今まで使っていたAPI がここで学んだAPI の基本設計を自然と取り入れられていたことに気づいた。

今まで自然と使っていたが、気づいていなかったことが多かったので非常に勉強になった。
そういう意味だけでもAPI 開発者としては読んでおくべき本かな、と思った。

また仕事で作っているAPI もこの基本設計は守っていつつ、
足りない部分もあったので反映していきたい。