Web API The Good Parts 1~2章の自分的まとめ
自分は本を読むのが遅いほうだが、最近は読んだ後に自分の中にあまり内容が残らないことが多くなってきた。。。
なので、これからは読んだ本があれば、随時自分の中でまとめたことをアウトプットとしてまとめていきたい。
今回、読んでいる本はこちら!
- 作者: 水野貴明
- 出版社/メーカー: オライリージャパン
- 発売日: 2014/11/21
- メディア: 大型本
- この商品を含むブログ (7件) を見る
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 にどのような権限を与えるか制御できる。
自サービスでログインを行う場合、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 もこの基本設計は守っていつつ、
足りない部分もあったので反映していきたい。