はじめに
本記事は「Web API The Good Parts」を読んでみての読書メモ兼感想です。
Youtubeやweb記事で時折みる本だったので読んでみました。
内容としてはAPIを作る上で基本的な部分を中心に書かれていました。また、AmazonやXが提供するAPIを例として用いているためスタンダードを理解しやすい、難易度的に読み易い本でした。
APIを作る際に気を付ける50のこと
Web APIとは何か、Web APIを作ることの利点から始まり、作り方、バージョン、セキュリティについて説明し、最終的にはAPIを作る際に気を付けるべき50のチェック項目ができている。
この本があればAPIを作る際に良いAPIなのかチェックできるようになる。
この中からいくつかまとめる
エンドポイント
Web APIを作成する際にエンドポイントを何にするかよく迷う。構造的に、意味のある文字で、短く端的に、小文字で程度のことはわかるがそれ以外にも則った方が良いルールがいくつかあった。
多く使われている表現を使う
例えばユーザー登録、取得など個々のデータに関するエンドポイントは下記のようなものが見られる。
| サービス | エンドポイント |
|---|---|
| /statuses/retweets/000999888777.json | |
| /xompanies/111222333 | |
| Foursquare | /venues |
ここに/listを付けたり、複数形にすることで一覧取得とするパターンは多い。
英語ネイティブではないので、ズレた意味の単語を使わないためにもよく使われている表現は押さえておきたい。
単語を繋げる際の表現
単語を繋げる際の表現はキャメルケース、スネークケース、ケバブケース、ドットつなぎなど様々である。実際どれも使用例がある。
| サービス | ルール | エンドポイント |
|---|---|---|
| スネーク | /statuses/user_timeline | |
| YouTube | キャメル | /guideCategories |
| ドット | /me/books.quotes | |
| ケバブ | /v1/people-search |
実際どれが良いかとなるとケバブケースである。アンダーバーはホスト名の部分で使えず、ドットは特別な意味を持ち、大文字小文字が混ざらない形となると残るはハイフンだけになる。また、GoogleがSEOの面からハイフンを推しているので特に理由がなければケバブケースにするのが良いだろう。
しかし、本当にベストなのは単語をくっつけないで済むよう、階層を分けたり単語を選ぶのが良いだろう。
パスパラメータとクエリパラメータ
リクエストパラメータの情報でこの２つはパスに入れてもクエリパラメータとして送っても設計上は可能だ。この２つの明確な区別を２つ紹介する。
- 一意なリソースを表すのに必要な情報か
URIはリソースを表すという元来の思想からきている。userIdはリソースを一意に特定する、トークンは認証なのでリソースとは関係がない。これでuserIdとトークンについてそれぞれどちらが適しているか説明できる。 - 省略可能か
検索項目のパラメータはない場合はデフォルトなことが多いので、この場合は、なくても大丈夫なパラメータとしてクエリパラメータが適している
レスポンスデータ
掲示板アプリを作ろうとした際に、実体験として困った箇所が多くありその解が載っていた。
続きがあるデータ
100件200件とデータの数が多い場合は途中までをクライアントに返します。その場合、どこまでのデータを送っているのかという情報が必要になりますが、この際に相対位置で取得すると計算量が多くなったり、データの挿入があった際に不整合が起きてしまうので、絶対位置でデータを取得するようにしましょう。
また、レスポンスデータの中に次があるのかという情報や、次のページ取得に必要なパラメータも一緒に返すというやり方もあります。
データの形
- 性別
0 / 1の2値で表すのか、3値で表すのか、それよりも多くとるのかということは sex と gender の違いで表されます。生物的性別であるsexの場合は2値または3値、社会的性別であるgenderの場合は文字で表されることが多いです。 - 日付
日付にはRFC822（Sun, 06 Nov 1994 08:49:37: GMY）、RFC850（Sunday, 06-Nov-94 08:12:49 GMT）、RFC3339（2015-10-12T11:12:30+09:00）、Unixタイムスタンプ（1396821803）とさまざま表し方がありますが、RFC3339（2015-10-12T11:12:30+09:00）が推奨されるようです。これは、年から秒までを略さずに表せ、言語に依存して尚且つ冗長である曜日が排除されているからです。
セキュリティ
フレームワークを利用していると、セキュリティを自動で守ってくれると捉えがちですが、
実際にはフレームワークは最低限の防御を提供しているだけで、API設計者自身が脅威モデルを理解しておく必要がある。Web API開発で特に注意すべき代表的な脅威とその対策を整理する。
パケットスニッフィング（Packet Sniffing）
脅威
通信途中で悪意ある第三者がデータを盗聴し、ログイン情報やトークン、個人情報などが漏洩する危険がある。
HTTP通信は平文でやり取りされるため、通信経路上で内容を簡単に解析される。
対策
- TLS(HTTPS)の使用
サーバー証明書を正しく設定し、HTTPアクセスをすべてHTTPSへリダイレクト。
Let’s Encryptなどを利用すれば無料で証明書を発行できます。 - HSTS（HTTP Strict Transport Security）ヘッダーを設定
一度HTTPSでアクセスしたクライアントは、以降すべてHTTPS通信を強制されるため安全性が向上。
XSS（クロスサイトスクリプティング）
脅威
悪意あるスクリプトがHTML内に埋め込まれ、利用者のブラウザで実行されてしまう攻撃。
Cookieの盗難やフォームの書き換え、セッションの乗っ取りなどにつがなる。
対策
- Content-Typeの明示
X-Content-Type-Options: nosniff
まとめ
全体として、ベストプラクティスを短時間で把握できる一冊でした。
既に開発経験がある人も、自分の設計が標準的な考え方に沿っているかを見直す良いチェックリストになると思います。