API初心者の「Web_API_The_Good_Parts」の感想
実務でAPIに触れることがあったものの、独学の時には全く触ってこなかったのでツケが回ってきた。
流石に理解しとかないとヤバいと思い、会社のWEB本棚にあった
Web_API_The_Good_Partsを読み始めたので、超雑に要点とか感想とか書く
筆者のレベルは、「APIになにそれおいしいの？」状態ということを念頭において読んでねw
(随時更新していきます)
1章 WEB API とはなにか
・APIは、機能はわかってるけれどもその中身の実際の動作は詳しくわからない(知らなくてもよい)機能のカタマリを、外部から呼び出すための仕様のことを指す
・APIエコノミー → Web API を公開することで外部サービスとの連携を容易にして新たな価値が生まれ、サービス やビジネスが発展していくこと
・APIは接着剤みたいな働きをする。サービスを拡大するには汎用性の有る仕組みがいる
・APIを作る場合、自分がユーザーにならないケースが多く想定されるので、美しい設計をする必要がある。仕様変更しやすいように変更しやすく、誰が使ってもセキュリティがしっかりとしている必要があり、他人に見られることを考慮して作ろう
・下記に従うことで、あなたの API を見たときにも、その利用方法が容易に類推可能になったり、あるいは既存のクライアントライブラリ の流用が可能になったりする
• 仕様が決まっているものに関しては仕様に従う
• 仕様が存在していないものに関してはデファクトスタンダードに従う
まとめ
• [Good] Web API を公開していないなら、すぐにその公開を検討する
• [Good] Web API を美しく設計する
• [Good] REST という言葉にこだわりすぎない
感想
・APIは、URLにアクセスすることで情報書き換えや取得するっていうのはあってた。
・確かにAmazonとかみんなアフィリンク貼るから、ネットにたくさんばら撒かれて流行るよな。
・APIを公開することで、そのAPIの成長につながることもある、いい世界
・普及されてる類似API(Pockert)とかがあったら、作るんじゃなくて利用させてもらったほうがユーザーのためになる、たしかに、Twitterに似たようなSNSできても、それTwitterでよくね？になるよなー
・他人が使いやすい読みやすい、美しいAPIを設計するように心がける
2章 エンドポイントの設計とリクエストの形式
・良いURLの設計は、覚えやすく、どんな機能を持つ URI なのかがひと目でわかる
わかりやすいURI ↓
• 短く入力しやすい URI
• 人間が読んで理解できる URI
• 大文字小文字が混在していない URI
• 改造しやすい(Hackable な)URI
• サーバ側のアーキテクチャが反映されていない URI
• ルールが統一された URI
・短く入力しやすい URI → service/api/search より /search
・人間が読んで理解できるURI → /seihin より /product
・大文字小文字) 略 → /getUserNameより /get_user_name
・改造しやすいURI → idによってかわるエンドポイント。諸説あるらしい
・サーバー側) 略 → get_user.php?user=100 ← ユーザーにとっていらない
・ルールが統一されたURI →friends/ と /friend を混合させると混乱を招く
・HTTPメソッド
→ GET メソッドはウェブへのアクセスで最も多く利用されているもので、「情報の取得」を表す
→ POST 新しい情報を登録するために利用する
→ PUT POST メソッドでは、送信したデータは指定した URI に “従属(subordinate)”したものになるが、PUT は送信するデータでもともとのリソースを完全に上書きする
→ PATCH データの一部だけを更新したい場合
→ DELETE リソースの削除を行うメソッド
・X-HTTP-Method-Override ヘッダ
→ものによっては、get、postしか使えないケースがあるので存在している
サーバ側のフレームワークやミドルウェアがこれらのヘッダやパラメー タを標準でサポートして自動的にその意味を解釈してくれる場合も多く、独自の方法で本来のメ ソッドを送信する場合と比較して、実装やテストの手間が軽減されることもメリット
エンドポイントを設計する中で注意すべき点
• 複数形の名詞を利用する
• 利用する単語に気をつける
• スペースやエンコードを必要とする文字を使わない
• 単語をつなげる必要がある場合はハイフンを利用する
まとめ
• [Good] 覚えやすく、どんな機能を持つかがひと目でわかるエンドポイントにする
• [Good] 適切な HTTP メソッドを利用する
• [Good] 適切な英単語を利用し、単数形、複数形にも注意する
• [Good] 認証には OAuth 2.0 を使う
感想
・URIを設定する上でも、相当意識して作る必要がある(KONAMI感)
・patchとputがあいまいだったが、全て更新するのはput、一部はpatchと覚えた。putのときのデータが大きいのに一部の更新ならputは非効率。
・oauthはログイン機能作る上で避けて通れない
3章 レスポンスデータの設計
・json → デファクトスタンダード
理由 → JSONのほうがシンプルで同じデータを表すのにサイズが小さくてすむこと、そしてウェブの世界においてはクライアントのデフォルト言語であるJavaScript との相性がとてもよい
・XML → 名前空間やスキーマ定義の仕様がきちんと決まっていたり、要素に対して属性を付けら れるなど JSON に比べて表現力は豊かですが、現状 Web API でやりとりされているデータの多く は JSON のシンプルなキーと値、および配列を使って表現可能であり、XML のより複雑な仕様を ほとんど必要としない
・レスポンスデータは選べるようにする
→情報が多すぎても少なすぎてもAPIに負荷やユーザーに負荷がかかるので、選択して取れるようにする
・Jsonではスネークケースが主流
→ Jsがスネークケースよく使うから
・IDが巨大すぎるとJSONとJSで誤差が出るので、文字列として返す
・ステータスコードはしっかりとクライアントに返す
→ (200成功系、400クライアント系、500サーバー系) ← 流石にこれは知ってた
・存在を知られてはダメな場合にあえて404で隠したりする。
→403エラー出すと、存在を認知される。
まとめ
• [Good] JSON、あるいは目的に応じたデータ形式を採用する
• [Good] データを不要なエンベロープで包まない
• [Good] レスポンスをできるかぎりフラットな構造にする
• [Good] 各データの名前が簡潔で理解しやすく、適切な単数複数が用いられている
• [Good] エラーの形式を統一し、クライアント側でエラー詳細を機械的に理解可能にする
感想
性別はgenderよりsexのほうが良いのかー。医療系はsex、SNSはgenderなど。
全く関係ないけど、整数の可能数字が2147483647なのパズドラで見たことあったけど、(ダメージカンスト)、32ビットで表現できる数がそれなのね。
正直この章はもう一度読み返して追記します。
4章 HTTPの仕様を最大限利用する
・200は成功系、300はリダイレクト、400はクライアント、500はサーバー
→ 細かいところまで書いてあったが省略。使う時に学べばいいかな、覚えられん、これ毎回みればおk
https://gist.github.com/rosylilly/3401612
・401 は認証(Authentication)のエラー、403 は認可(Authorization)のエラーを表します
→あえて403でも404にしたりするよね
・キャッシュのメリット
• サーバへの通信を減らすことができるため、ユーザーの体感速度を上げることができる
• ネットワーク接続が切れた状態でもある程度サービスを継続できる
• サーバへの通信回数、転送量を減らすことでユーザーの通信コストを下げることができる • サーバへのアクセス回数が減ることで、サーバの維持費用を抑えることができる
例) 気象情報返すAPI → 過去のデータが変更する可能性がないのでキャッシュ
・HTTP の キャッシュには Expiration Model(期限切れモデル)と Validation Model(検証モデル)とい う 2 つのタイプがあります
→ 期限設定か、最新のやつが更新されたらとってくるか
・ちなみにキャッシュが利用可能な状態を HTTP では“fresh”(新鮮)、そうでない状態を“stale” (新鮮ではない)と呼びます。
・Content-Type ヘッダを使ってメディアタイプを指定するのは非常に重要
→ Content-Type の値を使ってデータ形式をまずは判断しており、その指定を間違えるとクライアントが正しくデータを読み出すことができないケースが出てくるから
まとめ
• [Good] HTTP の仕様を最大限利用し、独自仕様の利用を最低限にとどめる
• [Good] 適切なステータスコードを用いる
• [Good] 適切な、なるべく一般的なメディアタイプを返す
• [Good] クライアントが適切なキャッシュを行えるように情報を返す
感想
ステータスコードの歴史を学べた
Contet-typeを指定する必要があるのか、SpecでもAPIを連携する時は、headerに
get hoge_path, headers: { CONTENT_TYPE: 'application/json', ACCEPT: 'application/json' }
みたいに書こう
細かったこの章も、また復習する。
5章 設計変更をしやすいAPIを作る
5-1 設計のしやすさの重要性
・APIをバージョンで管理する
→ 古 と 新 で、対応できるようにバージョン毎管理しないと積む
まとめ
• [Good] API のバージョンの更新は最低限にとどめ、後方互換性にも注意する
• [Good] API のバージョンはメジャーバージョンを URI に含める
• [Good] API の提供終了時はすぐに終了するのではなく最低 6 ヶ月公開を続ける
感想
v1とv2とかってバージョン1とかの略だったのか(今更)
APIはユーザーによってバージョン管理することでアップデートできる。バージョン管理は神
まとめに書かれてることがほぼ全内容で、例が多い章だった
6章 堅牢なAPIを作る
・HTTPではなくHTTPSを使う
・XSS 対策 → Contet-typeでjsonを返す、X-Content-Type-Optionsを用いるなど
・XSRF対策 → 1.GETではなくPUTやDELETEを使う、2.XSRFトークンを使う、3.“X-Requested- With”を使う
・JSONハイジャックに気をつける
まとめ
• [Good] 個人情報など特定のユーザー以外に漏洩したくない情報がある場合は HTTPS を 使う
• [Good] XSS、XSRF など通常のウェブと同様のセキュリティだけでなく JSON ハイジャッ クなど API 特有の脆弱性に気を配る
• [Good] セキュリティ強化につながる HTTP ヘッダをきちんと付ける
• [Good] レートリミットを設けることで一部のユーザーによる過度のアクセスによる負荷
を防ぐ
感想
HTTPSで100%防げるわけではないが、かなり有効
不正利用予想しつくさないと死ぬ
難しいところも多かったですが、実際にAPIを構築する時に見返したいと思える本でした。
