Web API The Good Partsのまとめです。Web APIの良い設計方法について書かれた本です。章構成はそのままですが、各章の中身は自分で勝手に構成していて、自分の考えも含まれます。前回の記事投稿から1年以上経過してしまいました...

1章 Web APIとは何か

Web APIとは「HTTPプロトコルを利用してネットワーク越しに呼び出すAPI」のことを言います。そもそもAPIというのは、「中身の動作は詳しく分からないような機能を外部から呼び出すための仕様」を指しており、Web APIに限らず、Material UIなどのUIライブラリもAPIに含まれます。しかし、単にAPIという時、多くの場合でWeb APIを指しているように思います。以降、この記事ではAPIをWeb APIを指すものと扱うことにします。

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

APIにアクセスする時、HTTPメソッドとエンドポイントを指定する必要があります。HTTPメソッドは操作方法、エンドポイントは操作する対象を表します。

HTTPメソッドについて

HTTPメソッドには以下が存在します。

GET

リソースの取得を表すHTTPメソッドです。GETを使ったアクセスでサーバ上のデータが書き換わることは基本的にあってはいけません(メッセージの既読や最終アクセス日時を管理する場合を除く)。

POST

新しいリソースの作成を表すHTTPメソッドです。HTML4.0のFormタグはGETとPOSTしかサポートされていないため、Formタグを使う場合、情報の削除や更新もPOSTで行うのが一般的です。しかし、通常は情報の削除、更新は以下に示すDELETE、PUT、PATCHを利用します。

DELETE

リソースの削除を表すHTTPメソッドです。

PUT

リソースの更新を表すHTTPメソッドです。送信するデータで、情報を完全に上書きする時に利用します。

PATCH

リソースの一部分の更新を表すHTTPメソッドです。巨大なデータの一部分を更新する場合、PUTよりPATCHの方がスマートです。

エンドポイントについて

エンドポイントとはAPIにアクセスするためのURIのこと(より厳密にはURL)です。エンドポイントは利用者にとって理解しやすい必要があります。良いエンドポイントを設計するために重要な項目として以下があります。

短く入力しやすい

https://api.example.com/service/api/searchはapiという言葉がホスト名とパス名の両方に含まれていています。さらにserviceはapiと類似した言葉で余計です。これはhttps://api.example.com/searchと直すことが出来ます。

人間が読んで理解できる

https://api.example.com/uはAPIのURIであることは分かりますが、uが何を指しているのか不明です。usersの省略かもしれないですが、確信を持てません。英単語を省略すれば短く入力しやすくはなりますが、このように理解できなくなってしまうケースも発生します。省略せずに、https://api.example.com/usersと書くべきです。

大文字小文字が混在していない

https://api.example.com/Usersのように、大文字と小文字が混在していると間違いやすくなります。通常、全て小文字で表記します。大文字が混ざったエンドポイントに対するリクエストは404エラーで返すケースが多いようです。

改造しやすい(Hackable)

アイテムを管理するデータベースを2つに分割し、https://api.example.com/items/alpha/<id>とhttps://api.example.com/items/beta/<id>の2つのエンドポイントを作ったとします。利用者にとっては、idによる場合分けをする必要があり、不便です。サーバ側の都合はサーバ内で処理し、利用者に意識させないようにします。この例なら、https://api.example.com/items/<id>とすれば、<id>の部分を変更することで、全てのアイテムの情報を得ることができる(改造しやすい)ということが出来ます。

サーバ側のアーキテクチャが反映されていない

https://api.example.com/cgi-bin/get_user.php?id=100というエンドポイントはPHPで書かれたプログラムをCGIで起動していることが分かってしまいます。このようにサーバ側のアーキテクチャやディレクトリ構造はエンドポイントに反映させる必要はありません。利用者にとって必要ない情報であるのと、脆弱性を突かれる可能性があるためです。
https://api.example.com/users/<id>/friends/<id>というエンドポイントにDELETEメソッドでアクセスすることで、友達の削除が出来るとします。エンドポイントに含まれる2つ目のidは、ユーザテーブルのidを使うべきでしょうか、それとも友達関係を表すテーブルのidを使うべきでしょうか？答えは前者です。後者はサーバ側のアーキテクチャが反映されています。また、前者の方が、利用者にとって改造しやすいということが出来ます。

ルールが統一されている

友達の情報をhttps://api.example.com/friends?id=<id>で取得でき、友達とのメッセージをhttps://api.example.com/friend/<id>/messageで取得できたとします。前者では、idがクエリパラメータに含まれているのと、複数形の単語が利用されています。後者では、idがパスパラメータに含まれているのと、単数系の単語が利用されています。このようにルールが統一されていないと、格好悪いです。この例では、https://api.example.com/friends/<id>とhttps://api.example.com/friends/<id>/messagesに直すことが出来ます。

複数形の名詞を利用する

https://api.example.com/get-user/<id>のように、エンドポイントに動詞を含めるべきではありません。HTTPメソッドが操作を表し、エンドポイントが操作の対象であるからです。また、データベースのテーブル名に複数形を用いるのが適切であるように、エンドポイントでも複数形を用いるのが一般的です。例えば、userではなくusersを用います。集合を表す場合、複数形を用いるのが自然であるためです。

利用する単語に気をつける

エンドポイントでよく使われている英単語を使用することで、開発者にとってより理解しやすくなります。例えば、検索用のAPIのエンドポイントでよく使われる英単語はsearchであって、findではありません。

単語を繋げる時はハイフンを利用する

https://api.example.com/users/<id>/profile-imageのように単語を繋げる時はハイフンを利用します。プログラム中の変数では、アンダースコアを利用することがありますが、URI中のホスト名ではアンダースコアを用いることが出来ないため、ハイフンで統一する方が良いです。また、ウェブページではリンクに下線が引かれるため、アンダースコアを使うと、重なって見づらいという理由があります。

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

ページネーション

Twitterの投稿などのような大量のデータを一気に取得することは現実的ではありません。また、大量にデータを取得したとして、それを全て画面に表示すると見にくくなってしまいます。こういう時は、ページネーションを利用します。ページネーションとは、データの取得数と取得を始める開始位置をクエリパラメータで指定する仕組みです。SQLのSELECT文のLIMITとOFFSETに該当します。例えば、https://api.example.com/posts?per-page=50&page=3は50件のデータを1ページとし、3ページ目を表します。https://api.example.com/posts?limit=50&offset=100は101件目から150件目のデータを表します。pageが1-indexed、offsetが0-indexedであることが一般的です。page、offsetは先頭からの相対位置ですが、相対位置を利用する場合、バックエンド側のパフォーマンスの問題が生じます。SQLのOFFSETは先頭から順にデータを数えていく処理が行われるためです。絶対位置を利用する場合、この問題は起こりません。例えば、https://api.example.com/posts?limit=50&since_id=100はidが100から149のデータを表します。since_idにインデックスが付与されている場合、SQLクエリは高速に処理することが出来ます。

クエリパラメータ

検索のクエリパラメータとしてqがよく使われます(queryの略)。qは全文検索のニュアンスがあり、例えばhttps://api.example.com/users?name=kenは名前がkenに一致するユーザを表しますが、https://api.example.com/users?q=kenはユーザ情報のどこかにkenを含むユーザを表すのが一般的です。Googleの検索もクエリパラメータとしてqを使っており、指定した単語が含まれるページが検索結果として表示されます。

OAuth

TwitterやGitHubなどの外部サービスのアカウントでログインできるサービスが多いです。これを実現するのがOAuthと呼ばれる仕組みです。OAuthでは、以下の4つが登場します。

ユーザ
クライアントアプリ(外部サービスに対するクライアントという意味でクライアントアプリです)
リソースサーバ(外部サービスのサーバ)
認可サーバ(リソースサーバへのアクセス権限を与えるサーバ)

OAuthは以下の流れで進行します。

ユーザがクライアントアプリに外部サービスとの連携を指示します。
ブラウザに外部サービスの認証画面が表示されます。
ユーザは外部サービスで認証情報を入力し、クライアントアプリが外部サービスのユーザ情報にアクセスすることを許可します。
認可サーバからブラウザに認可コードが渡されます。
ブラウザからクライアントアプリに認可コードを渡します。
クライアントアプリは認可コードを使い、認可サーバからトークンを受け取ります。
クライアントアプリはトークンを利用して、リソースサーバからユーザ情報を手に入れます。

外部サービスの認証情報をクライアントアプリに与えることなく、クライアントアプリが外部サービスのリソースにアクセスできるようになる仕組みになっています。7ではトークンをAuthorizationヘッダに含める方法、リクエストボディに含める方法、クエリパラメータとして指定する方法がありますが、Authorizationヘッダに含めるのが一般的だと思います。トークンには有効期限があり、有効期限切れになった場合、クライアントアプリは再度、認可サーバからトークンを受け取る必要があります。
OAuthには外部サービスのリソースにアクセスするための仕組みが複数あり、これはGrant Typeと呼ばれます。上の流れはGrant TypeがAuthorization Codeの場合です。他のGrant TypeのOAuthの流れは、Authlib で OAuth 2.0 の仕組みや使い方を学ぶ | ほげほげテクノロジーやOAuth Grant Types 概要 - Qiitaを参考にすると良いと思います。

SSKDs向けのAPIデザイン

SSKDsはSmall Set of Known Developersの略で、既知の少数の開発者という意味です。これと対をなす言葉として、未知のたくさんの開発者を意味するLSUDs(Large Set of Unknown Developers)があります。LSUDs向けのAPIは、様々なユースケースを想定し、なるべく汎用的で、分かりやすいようにするべきです。SSKDs向けのAPIでもこれは大切ですが、それ以上にエンドユーザのことを考え、ある程度adhocに設計することが大切です。例えば、ECサイトのホーム画面には、新着の商品、人気の商品、レコメンド商品、カートに入れた商品、ログイン中のユーザ情報などが表示されます。これらの情報を異なるAPI(新着表品を取得するAPI、人気の商品を取得するAPI、...)で提供する場合、ホーム画面を表示するために、何度もAPIにアクセスする必要があり、長い時間ユーザを待たせてしまいます。そのため、ホーム画面用のAPIを用意し、1回のAPIアクセスでホーム画面を表示できるようにすると良いです。
画面を表示するためにAPI呼び出しを何回もしなければならないという問題は、APIにおける重要なトピックの1つだと思います。上で説明した解決策以外にも、GraphQLやBackends For Frontendsという仕組みがあります。

HATEOS

HATEOS(Hypermedia As The Engine Of application State)とは、APIのレスポンスに、次にアクセスするべきエンドポイントと、そのエンドポイントとの関係を含めるというAPI設計の方法です。クライアントがエンドポイントを予め知る必要がないため、エンドポイントの変更がしやすい、エンドポイントを改造しやすくする必要がない、というメリットがあります。しかし、あまり普及した設計方法とは言えません。

3章レスポンスデータの設計

データフォーマット

APIを通じてやり取りするデータフォーマットはJSONを用いるのが一般的です。昔はXMLが使われていましたが、JSONの方がシンプルであることと、JavaScriptとの相性が良いことから、JSONが使われるようになりました。

JSONPについて

JSONPとは同一生成元ポリシーを突破するための方法です。まず同一生成元ポリシーとは、異なるオリジンへのアクセスを禁止するものです。オリジンは、スキーム、ホスト、ポート番号の組合せです。例えば、https://a.example.comとhttps://b.example.comはスキームはhttpsで同じですが、ホストが異なるため、異なるオリジンです。ポート番号はスキームから分かるため、基本的に省略されます(ウェルノウンポート)。例えば、HTTPSの場合、ポート番号は443番が用いられます。ローカル環境で開発をする場合、localhost:3000やlocalhost:8000のようにポート番号を含み、これらはポート番号が異なるため、異なるオリジンです。同一生成元ポリシーは、CSRFのようなセキュリティ攻撃を防ぐために考えられました。
JSONPは少し複雑な仕組みをしています。scriptタグに同一生成元ポリシーが適用されないことを利用します。Webページ側では、コールバック関数を用意し、コールバック関数の名前をクエリパラメータとして、APIを呼び出します。以下はその例です。

<script>
const cbfunc = (data) => {
	console.log(data.name);
	console.log(data.age);
};
</script>
<script src="https://api.example.com/users/1?callback=cbfunc">

バックエンド側では、クエリパラメータからコールバック関数の名前(cbfunc)を取り出し、cbfunc({"name" : "Taro", "age" : 20})というJavaScriptコードを返却します(レスポンスのContent-Typeヘッダはapplication/javascript)。これによって、cbfuncが実行されます。より詳細な実装は、4ステップで作って学ぶJSONPが参考になります。
JSONPは使うべきではありません。同一生成元ポリシーが防いでくれているセキュリティ攻撃を認めることになるためです。オリジンを跨いだアクセスはCORS(Cross Origin Resource Sharing)という仕組みで管理されるべきです。多くのWebフレームワークはCORSの機能を備えており、JSONPを使うよりも実装は簡単です。

レスポンスデータの設計方法

APIのレスポンスを設計するためには以下が重要になります。

ChattyなAPIを作らない

例えば、https://api.example.com/users/<id>/friendsにGETメソッドでアクセスした時に、以下のような友達のユーザIDの配列のみを返したとします。

{
  "friends" : [
    234342,
    93734,
    197322,
    ...
  ]
}

しかし、クライアント側では友達のユーザIDだけでなく、名前やプロフィールアイコンも表示することが一般的です。そのため、友達のユーザIDそれぞれについて、https://api.example.com/users/<id>にGETメソッドでアクセスする必要があります。APIアクセスの回数が増加するため、長い時間ユーザを待たせるだけでなく、クライアント側の開発者にとっても不便です。このようなAPIはChattyなAPIと呼ばれます。

レスポンスの内容をユーザが選べるようにする

ChattyなAPIの回避策として、できる限り多くの情報をレスポンスを返す、という方法があります。しかし、クライアントに必要のない情報を大量にレスポンスに含むのはネットワークのトラフィックを増加させてしまいます。このような場合、クエリパラメータで必要な情報を指定できるようにします。例えば、https://api.example.com/users/<id>/friends?field=name,profile-iconです。このエンドポイントにGETメソッドでアクセスした時は以下のようなデータを返すようにします。

{
  "friends" : [
    {
      "id" : 234342,
      "name" : "Taro",
      "profileIcon" : "https://s3.us-west-2.amazonaws.com/..."
    },
    ...
  ]
}

エンベロープをレスポンスボディに含めない

エンベロープとは、APIのレスポンスに共通するデータ部分です。例えば、ステータスコードが挙げられます。エンベロープをレスポンスボディに含めることを考えます。以下のJSONのheader部分がエンベロープになります。

{
  "header" : {
    "status" : "success",
    "errorCode" : 0
  },
  "response" : {
    ...
  }
}

HTTPにはヘッダの概念があり、ヘッダがエンベロープの役割を担っています。そのため、エンベロープはレスポンスボディではなく、レスポンスヘッダに含めるべきです。また、HTTPのクライアントライブラリはレスポンスヘッダのステータスコードを見て振る舞いを決めるため、レスポンスボディにステータスコードを含めるべきではありません。

データをフラットにするべきか

メッセージのやり取りを表すレスポンスボディの形を考えます。階層的に表す場合は以下のようになります。

{
  "id" : 3342124,
  "message" : "Hi!",
  "sender" : {
    "id" : 3456,
    "name" : "Taro"
  },
  "receiver" : {
    "id" : 12912,
    "name" : "Suzuki"
  }
}

対して、フラットに表す場合は以下のようになります。

{
  "id" : 3342124,
  "message" : "Hi!",
  "senderId" : 3456,
  "senderName" : "Taro",
  "receiverId" : 12912,
  "receiverName" : "Suzuki"
}

どちらが良いでしょうか？senderとreceiverのように同じユーザを表す場合は、階層構造にした方がクライアント側で処理しやすいかもしれません。
しかし、以下のように複数項目をまとめるためだけに階層構造にするのはあまりメリットがありません。

{
  "id" : 23245,
  "name" : "Taro",
  "profile" : {
    "email" : "taro@gmail.com",
    "gender" : "male",
    ...
  }
}

レスポンスボディを配列ではなくオブジェクトにする

配列をレスポンスボディにすることもできますが、以下の理由から配列をvalueにしたオブジェクトとして返す方が良いです。

keyによって、レスポンスが何を表しているか分かるようにする
レスポンスデータをオブジェクトに統一し、クライアント側の負担を減らす
JSONインジェクションの防止(JSONPを使う場合)

JSONインジェクションの詳細は割愛します。そもそもJSONPを使わなければ、発生しない脆弱性です。

ページネーションで続きがあるかのフラグを返す

ページネーションを利用する時、クライアント側で「次のデータを表示」というリンクを表示するためには、レスポンスに次のデータがあるかのフラグを含める必要があります。バックエンド側で、必要な件数+1件を取得することが出来れば、次のデータがあることが分かります。

キー名に気をつける

JSONのキー名を決める時は以下の項目が重要になります。

キャメルケースを使用する
多くのAPIで使われている単語を使用する
なるべく少ない単語数で表現する(例えばregistrationDateTimeよりもcreatedAt)
変な省略形を使わない(例えばtimelineをtlと略すなど)
valueが配列の場合は複数形、オブジェクトの場合は単数形にする

JavaScriptの命名ではキャメルケースを用いるのが多いため、キー名もキャメルケースを使用するのが良いです。

日付のフォーマットではRFC3339を用いる

日付のフォーマットでは基本的にRFC3339を用いるのが良いです。RFC3339は2015-10-12T11:30:22+09:00のように日付を表し、JanやFriのような特定の言語に依存しません(例えばRFC822ではSun, 06 Nov 1994 08:49:37 GMTのように日付を表します)。SSKDs向けのAPIであれば、Unixタイムスタンプを利用しても良いです。Unixタイムスタンプとは1970年1月1日0時0分0秒からの経過秒数です。残念ながら、HTTPヘッダではRFC822, RFC850, ANSI Cのasctime()形式しか使えません。

非常に大きな整数は文字列にする

JavaScriptでは非常に大きな整数を扱おうとすると誤差が発生します。例えば、以下のコードの出力は462781738297483260になってしまいます。

console.log(462781738297483241);

これはJavaScriptが数値を全てIEEE754の64ビット浮動小数点数として扱うためです。そのためこのような整数は文字列として扱うのが良いです。

オブジェクト構造を決めておく

オブジェクトの構造を決めておくことで、クライアント側の開発が楽になります。例えば、ユーザ情報はidと名前とメールアドレスから成るとします。これによって、TypeScriptで以下のような型を作ることができます。

type User = {
 id: number;
 name: string;
  email: string
};

https://api.example.com/users/<id>にGETメソッドでアクセスした時のレスポンスボディは以下のようにします。

{
  "id" : 123,
  "name" : "taro",
  "email" : "taro@gmail.com"
}

こうすることで、レスポンスボディをそのままUser型の変数に代入することが出来ます。

エラーの詳細を伝える

ステータスコードでエラーを伝えるだけでなく、エラーの詳細をクライアントに伝える方が親切です。例えば、ステータスコード404が返ってきた時、エラーの詳細が与えられないと、クライアントはエンドポイントを間違えたのか、それとも指定したデータが存在しないのかが分かりません。エラーの詳細は、多くのサービスで、ヘッダではなくレスポンスボディに含められています。エラーの詳細として、エラーの詳細コード(ステータスコードよりも細かい粒度)、エラーメッセージ、詳細情報へのリンクを含めると良いです。

エラーの際にHTMLが返ることを防ぐ

サーバ側のプログラムにバグがあって、処理が停止してしまった場合、利用しているWebサーバがエラーを返しますが、デフォルトではHTMLでエラーが返るようになっていることが多いです。しかし、クライアント側はJSONを期待しており、HTMLが返ってくると、パースエラーでクライアント側もエラーを起こしてしまいます。こうならないよう処理が停止した場合でも、JSONが返るようにします。Nginxの場合、nginx エラーページでjsonを返す方法 - Qiitaが参考になりそうです。

サービス停止時はRetry-Afterヘッダを返す

サービス停止時はステータスコード503を返すと同時にRetry-Afterヘッダで、アクセス可能になる時刻、または、アクセス可能になるまでの秒数を入れます。

意図的に不正確な情報を返す

例えば、ログインの際にメールアドレスとパスワードを送信した時に、そもそもメールアドレスが存在していないことが分かるとユーザにとって親切ですが、そのような情報は悪意を持ったユーザにも情報を与えてしまいます。「与えられた認証情報は存在しない」という曖昧なレスポンスの方が安全と言えます。

4章 HTTPの仕様を最大限利用する

ステータスコードについて

ステータスコードのおよその意味合いは以下のようになっています。

200番台 : 成功
300番台 : リダイレクト
400番台 : クライアント側に起因するエラー
500番台 : サーバ側に起因するエラー

さらに詳しく見ていきます。

200番台

200 OK : リクエストが成功した時に使います。
201 Created : リクエストの結果、サーバ側でリソースが作成された時に使います。　
202 Accepted : 処理を受け付けたけど、完了していないことを意味します。時間がかかる処理について、一旦クライアントにレスポンスを返したい時に使います。
204 No Content : レスポンスボディが空の時に使います。本では、PUT、PATCHの場合、ステータスコード200とともに、更新後のデータをレスポンスボディに含み、DELETEの場合、ステータスコード204を返すと良いと書かれていて、自分もそう思いました。

300番台

300 Multiple Choices : 指定したエンドポイントが取得するデータを一意に特定するには曖昧である時に使います。滅多に使われません。
301 Moved Permanently, 302 Found, 303 See Other, 307 Temporary Redirect : リダイレクトを指示する時に使います。Locationヘッダにリダイレクト先のURLが含まれます。リダイレクトは、ページが移転した場合や、Formタグでデータを送信した後にページをリロードすると、データが再送されてしまうことを防ぐために用いられます。
304 Not Modified : 前回のデータ取得から更新されていない時に使います。

400番台

400 Bad Request : 送られてきたパラメータが不正である時に使います。
401 Unauthorized : セッション情報が送られて来なかったり、間違ったセッション情報が送られて来て、認証に失敗した時に使います。
403 Forbidden : 一般ユーザが管理者しかアクセスできない情報にアクセスをしようとするなど、許可されていない操作をしようとした時に使います。
404 Not Found : アクセスしようとしたデータが存在しなかったり、存在しないエンドポイントにアクセスした時に使います。
405 Method Not Allowed : エンドポイントは存在しているが、メソッドが許可されていない時に使います。
406 Not Acceptable : クライアントが受け取りたいデータ形式にAPIが対応していない時に使います。
408 Request Timeout : クライアントがリクエストを送るのに時間がかかりすぎた時に使います。
409 Conflict : ユーザ登録の時に、既に同じアドレスのユーザが存在していたなどのリソース競合が発生した時に使います。
410 Gone : アクセスしたリソースが過去にあったが、今は存在しない時に使います。
413 Request Entity Too Large : リクエストボディが長すぎる時に使います。
414 Request URI Too Long : クエリパラメータが長すぎる時に使います。
415 Unsupported Media Type : クライアントが送ってきたデータ形式にAPIが対応していない時に使います。
429 Too Many Requests : アクセス回数がレートリミットを超えた時使います。

500番台

500 Internal Server Error : サーバ側のプログラムにバグがあって、処理が停止してしまった時に発生します。
503 Service Unavailable : サービスがメンテナンスで一時的に利用できない時に使います。

クライアントキャッシュ

Expiration Model (期限切れモデル)

レスポンスに保存期限を決めておいて、期限が切れたら、再度アクセスして取得を行います。保存期限はCache-Controlヘッダで指定する方法とExpiresヘッダを使う方法があります。Cache-Controlヘッダには、レスポンスが生成された時刻からの秒数を指定し、Expiresヘッダには、期限切れの時刻を指定します。

Validation Model (検証モデル)

クライアント側が持っているキャッシュが有効であるかをサーバに問い合わせます。クライアント側からは最終更新日時またはETagが送られます。ETagはリソースのハッシュ値です。最終更新日時の場合はIf-Modified-Sinceヘッダ、ETagの場合はIf-None-Matchヘッダを用います。サーバ側でチェックを行い、リソースが更新されていた(=キャッシュが有効でない)場合はステータスコード200とともに更新されたデータを返します。そうでない場合はステータスコード304を返します。

CORS

CORSはオリジンを跨いだアクセスのための仕組みです。クライアントはOriginヘッダに自身のオリジンを指定します。これはブラウザが自動で行います。サーバ側では、アクセスを許可するオリジンの一覧を保持しておいて、そこにOriginヘッダで指定されているオリジンが含まれているなら、Access-Control-Allow-OriginヘッダにOriginヘッダで指定されているオリジンを指定して返すことで、アクセスを許可したことを伝えます。含まれていない場合はステータスコード403を返します。
クライアントから「単純でない」リクエストを送信する時は、そのリクエストが受け入れられるのかチェックするためにプリフライトリクエストと呼ばれるリクエストが送信されます。以下のいずれかの条件を満たすとき、リクエストは単純ではありません。

利用するHTTPメソッドがHEAD, GET, POST以外
以下のヘッダ以外のヘッダを送信しようとしている
- Accept
- Accept-Language
- Content-Language
- Content-Type
以下のメディアタイプ以外のメディアタイプをContent-Typeヘッダに指定している
- application/x-www-form-urlencoded
- multipart/form-data
- text/plain

プリフライトリクエストはOPTIONSメソッドで送信されます。GoのCORSパッケージはhttps://github.com/rs/cors/blob/master/cors.goです。コードを読んでみると、プリフライトリクエストの場合はリクエストを許可しない場合でも、ステータスコード200を返しますが、Access-Control-Allow-Originヘッダが空で返されるため、ブラウザはリクエストを止めるはずです。プリフライトリクエストでない場合はOriginヘッダの検証はするものの、許可されたオリジンに含まれていない場合は、403を返すなどせず、普通にリクエストを処理しています。恐らく、HTMLファイルを返すようなエンドポイントがある時、それを参照するaタグのリンクは同一生成元ポリシーを適用する意味がないため、このような実装になっていると考えています。しかし、API側の実装でクエリパラメータでトークンを指定できるようになっていると、全てのオリジンからhttps//api.example.com/users/me?token=...にGETメソッドのリクエストが通ることになり、CSRFが成立しそうに思います。実際にこのような記事が見つかりました。

5章設計変更をしやすいWeb APIを作る

一度公開したAPIは出来るだけ変更しない方が良いです。突然、レスポンスの形が変わったら、利用者は混乱するでしょう。では全く変更が出来ないのかと言うとそうではなく、新しいエンドポイントで変更後のAPIを公開すれば良いです。このために、APIをバージョン番号で管理します。バージョン番号はエンドポイントの中に入り、https://api.example.com/v1/...のような形式が最も一般的です。
バージョニングの手法として、セマンティックバージョニングというものが知られています。セマンティックバージョニングでは、バージョンを1.2.3のような3つの数字で表し、左からメジャー、マイナー、パッチと呼ばれ、以下のルールが適用されます。

パッチはAPIに変更がないようなバグ修正を行った時に増える
マイナーは後方互換性のある変更を行った時、または特定の機能が今後廃止されることが決まった時に増える
メジャーは後方互換性のない変更を行った時に増える

「後方互換性がある」とは、昔のコードがそのまま動く、つまりクライアント側の変更を要請しないことを言います。エンドポイントに含めるバージョン番号はメジャーになります。APIの変更時は出来るだけ後方互換性を保つようにし、メジャーを上げないようにします。
例えば、あるAPIのレスポンスに含まれるキー名をhogeからfugaに変更することになったとします。もし、レスポンスからhogeを削除してしまったら後方互換性が無くなることになりますが、hogeは残したままfugaを追加し、ドキュメントで「メジャー番号が上がった時にhogeは廃止されるから非推奨」ということを書くようにします。認証認可の仕組みを変えるなど、どうしても後方互換性が保てない変更では、メジャー番号を上げ、その時にキー名からhogeを削除するといった修正も行うようにします。

6章堅牢なWeb APIを作る

HTTPSを使う

HTTPSを使うと、エンドポイントやヘッダ、ボディ(リクエストとレスポンスの両方)が暗号化されます。逆にHTTPSを使わないと、暗号化されないため、誰でも通信内容を覗き見ることが出来てしまいます(パケットスニッフィング)。HTTPSを使っていても安全とは限らず、OpenSSLの例のように暗号化ライブラリにバグがあるケースがあります。他にもクライアント側がサーバから送られてくる証明書の検証を行なっていないと、中間者攻撃を受ける可能性があります。

XSS

XSSとは、ユーザからの入力をページに埋め込んで表示するときに、ユーザからの入力をJavaScriptとして処理してしまう時に発生するセキュリティ攻撃です。攻撃者は、XSSの脆弱性があるサイトAにスクリプトを埋め込んでおいて、そのページのリンクを攻撃対象のユーザに送信します。スクリプトの内容は、Cookieの中身を攻撃者のサーバに送信するといったものです。攻撃対象のユーザがリンクを踏んでページを開くと、埋め込まれたスクリプトが実行され、攻撃対象のユーザの個人情報などが攻撃者に渡るといった仕組みです。

悪意あるアクセスへの対策

認証に成功したユーザであっても不正を働こうとします。例えば、ゲームでアイテムを消費するAPIが実装されていた時、悪意あるユーザが、消費するアイテムの個数を負にしたようなリクエストを再現して送信すると、そのユーザのアイテムの個数は増えてしまいます。クライアントから送られてきた情報を信用せず、バリデーションを行う必要があります。
アプリ内課金でも、不正が発生する可能性があります。iOSの場合、アプリ内課金はAppleの支払い処理サービスを経由します。課金をすると、支払い処理サービスからクライアントにレシートと呼ばれる文字列が送信されます。レシートをリクエストに入れて、サーバに送信します。サーバ側ではレシートの正当性を支払い処理サービスに確認し、さらに同じレシートが過去に使われていないかを確認する必要があります。サーバ側でこれらの処理を行わない場合、悪意あるユーザは、正しい支払い処理時のリクエストを再現することで、何度もアプリ内課金を実行出来てしまいます。

roaris.io

すべての記事