1章 WebAPIとは何か？
美しく設計したほうが良い4つの理由
- 使いやすくするため…APIの利用者にとって使いやすいと感じないAPIは、そもそも公開する意味が薄れてしまう。
- 変更しやすくするため
- 頑強にするため…セキュリティの問題を考慮していること。
- 恥ずかしくないように…一般に公開する場合、API提供者の技術レベルが疑われる。良い技術者が集まりにくくなる可能性も。
2章 エンドポイントの設計とリクエストの形式
エンドポイント・URLの設計の原則
覚えやすく、どんな機能を持つURIなのかがひと目でわかる
2.2.1 エンドポイントの基本的な設計
この原則を知るだけでも、API設計時に闇雲にならずに済みますね。バックエンドチームのデスク周りに標語として貼り紙しておくと良いかもしれません。
・短く入力しやすいURI
2.2.1 エンドポイントの基本的な設計
・人間が読んで理解できるURI
・大文字小文字が混在していないURI
・改造しやすい（Hackableな）URI
・サーバ側のアーキテクチャが反映されていないURI
・ルールが統一されたURI
このリストがあるだけで、APIのURIの品質が担保できそうですね。
URIに困ったら、ProgrammableWebで公開されているAPIを参考にするのが近道だそうです。
エンドポイントを設計する中で注意すべき点をいくつか見ておきましょう。
2.4.1 リソースにアクセスするためのエンドポイントの設計の注意点
・複数形の名詞を利用する
・利用する単語に気をつける
・スペースやエンコードを必要とする文字を使わない
・単語をつなげる必要がある場合はハイフンを利用する
特定のパラメータをクエリパラメータに入れるか、パスに入れるかはURIを設計する上で決める必要が出てきますが、その判断基準は以下のようなものでしょう。
2.2.5 クエリパラメータとパスの使い分け
・一意なリソースを表すのに必要な情報かどうか
・省略可能かどうか
これはちゃんと教えてもらわないと迷うポイントですよね。SpringBootで個人開発しているときも、＠PathVariable か @RequestParam どっちで受け取るようにするか迷うことがあります。そんな時にこの内容を知っていれば一貫性を持って使い分けれそうです。
example.comというサービスでAPIを提供する際のホスト名はapi.example.comが最も適切であることがわかります。
2.7 ホスト名とエンドポイントの共通部分
3章 レスポンスデータの設計
APIのユースケースをよく考え、ユーザーが最もシンプルに扱うことができる設計を目指すこと。
データフォーマットはJSONで
主な理由としては、JSONの方がシンプルで同じデータを表すのにサイズが小さくてすむこと、そしてウェブの世界においてはクライアントのデフォルト言語であるJavaScriptとの相性がとても良いこと
3.1 データフォーマット
レスポンスは少回数、小サイズが良い
レスポンスはアプリケーションのユースケースに沿うようにする。IDだけレスポンスして、詳細はIDでまたAPIリクエストとはしない。IDと同時に詳細データも返す方が良い＝少回数＜テーブル構造が反映されている悪例。
少回数にすると、1レスポンス当たりのサイズが増えやすい。サイズが大きくなる場合は、クエリパラメータでレスポンス項目を選べるようにすると良い。＝小サイズの工夫。
AmazonのAPIではレスポンスグループをクエリパラメータで指定できる。これは、プレゼンテーション層（Controller内）の仕事になりそうですね。
不要な入れ子（エンベロープ）を作らない。次は不要な入れ子の例。
{
“data”: {
“hoge”: “hoge”,
}
}上記のようにしている案件もあるが、data は不要。
レスポンスの項目名（key）のルール
JSONではキャメルケースを使うのがよいとされています。なぜならJSONがベースとしているJavaScriptの命名規約において、キャメルケースの利用がルールつけされているケースが多いからです。Googleのスタイルガイドにも明記されています…
3.4.1 各データの名前
キャメルケースを使うようにしましょう。
{
◎ “siteName”: “SpringHack”
× “site-name”: “SpringHack”
}日付はRFC3339形式で
{
“createdAt”: 2021-02-02T11:30:22,
}ステータスコード 400はクライアントサイド由来、500はサーバー由来
公開されているAPIはほとんどボディにエラーメッセージを格納する方法をとっています。クライアント側から見たときの利便性などを考えるとボディのほうが処理が行いやすいからだと思われます。
3.6.2 エラーの詳細をクライアントに返す
エラーメッセージ等をレスポンスヘッダーに格納する方法もあるが、ボディに格納する方法で良い。
ボディに格納したエラー内容の例は下記。
{
“errors”: [{
“message”: “○○は××です。”,
“code”: 2020
}]
}4章 HTTPの仕様を最大限利用する
400(Bad Request)は他の400番台のエラーで表せないエラー
400（Bad Request）はいきなりではありますが「その他」つまり、他の400番台のエラーでは表すことができないエラーに使うためのステータスコードです。
4.2.3 クライアントのリクエストに問題があった場合
400BadRequest以外で業務システム開発で使いそうなのは、409(Conflict) …新規登録時のID重複や排他エラーは本来409です。
クライアント側でステータスコードごとの振る舞いを共通化しておけば、良いアプリになりそうですね。
409の場合は画面リフレッシュを促す、400の場合は入力値の変更を促すなど。
CORSエラーが起きたらサーバ側でAccess-Control-Allow-Originを設定する
XHTTPRequestは異なるドメインに対してはできない。同一生成元ポリシーというセキュリティ上のポリシーのため。
CORSになるかどうかは、スキーム、ホスト、ポート番号で判断される。
- スキーム（http と https ）が異なってもNG
- サブドメインが異なってもNG
- ポート番号が異なってもNG
CORSをする場合、
クライアントはリクエストヘッダーに “Origin: http://hoge.com/“を含める必要がある。
サーバは送られてきたOriginがアクセス許可リストに含まれるか判定し、OKならばレスポンスに”Access-Control-Allow-Origin: http://hoge.com/”を入れて返す。
5章 設計変更をしやすいWeb APIを作る
APIのバージョンはメジャーバージョンをURIに含める
5.6 まとめ
メジャーバージョンというのは、セマンティックバージョニングという考え方のトップレベルに位置するもの。”1.2.3”のように、メジャー・マイナー・パッチのを表す3つの数値をドットで繋ぎます。
- パッチバージョン…APIに変更がないバグ修正などを行なった時に増える。
- マイナーバージョン…後方互換性のある機能変更が行われた際に増える。
- メジャーバージョン…後方互換性のない変更が行われた際に増える。
業務システムではメジャーバージョンアップをするときは、システムごと刷新するときぐらいかもしれません。そうすると、システム名も変わってしまいそうですね。ですが、セマンティックバージョニングはグローバルな命名法なので、デベロッパーとして知っておいて損はないでしょう。内部のドキュメントのバージョンにも使えそうです。
どんな本か？
あなたが開発するものが公開するAPIか、社内用の非公開APIかに関わらず、APIを開発するなら必ず役に立つ本です。
API開発者なら最低限、本書の内容に一度は目を通しておくべきです。
小難しい言葉が使われていないので、とても読みやすいです。薄い本の中にベストプラクティスが凝縮されているので、効率良く勉強できます。
付録に2ページに渡ったWeb APIチェックリストがあるので、自分がAPIのURIや構造を決定する必要があるときは、これに基づいてチェックしていけば良いでしょう。
業務システムエンジニアも、本書に沿ってAPI設計をして行くことで、Web系に転職したくなった時のアピール材料や事前学習になるでしょう。
どんな人にお勧めか？
- バックエンドを設計・開発する人
- APIのURL設計で迷っていることがある人
- APIのURL設計の決定根拠が欲しい人
- OAuthを使用するシステムの設計者
- エラーコードどれを返すようにしよう？と迷ってる人
- CORSエラーに悩まされている・悩んだことがある人
- 適切なバージョンを振り方がわからない人
- 本記事記載内容の根拠や詳細が知りたい人
- アーキテクト・リーダーなど、開発方針を決定する立場にある人
- 真面目なエンジニア
短時間でAPI設計について要点をしっかり押さえることができるので、全エンジニアにおすすめです！！！
