普段アプリ開発業務をやりますが、バックエンド周りはからっきしで、APIの改修とかはそこそこやるもののなんかよくわからんけど動くっていう感じの知識量なので、Webサービスの設計について学ぼうと思いました。

参考書籍は以下。

これの第5部、15章がちょうど設計について学べそうだったのでまとめて行きます。

リソース設計のアプローチ

1️⃣ Webサービスで提供するデータを特定する
2️⃣ データをリソースに分ける
3️⃣ リソースにURIで名前をつける
4️⃣ クライアントに提供するリソースの表現を設計する
5️⃣ リンクとフォームを利用してリソース同士を結びつける
6️⃣ イベントの標準的なコースを検討する
7️⃣ エラーについて検討する

題材

参考書籍では、Web APIを中心とした郵便番号検索サービスを対象としています。

要件としては

・日本の郵便番号情報を提供する
　・郵便番号情報は、郵便番号 / 住所 / 住所の読み から成る
　・住所は、都道府県名 / 市区町村名 / 町域名 から成る
・郵便番号の前方一致で、郵便番号情報を検索できる
・住所 or 住所の読みで郵便番号情報を全文検索できる
・データは全て読み取り専用

1️⃣ Webサービスで提供するデータを特定する

自分のサービスでどのようなデータを提供するのかを理解しないとそもそも設計できない。

当たり前だけど大事。。

題材で使ってるサービスでは、下記のデータを使っているようです。

【データ名】：【データ型】
郵便番号(7桁)：半角数字
都道府県名：半角カタカナ
市区町村名：半角カタカナ
町域名：半角カタカナ
都道府県名：漢字
市区町村名：漢字
町域名：漢字

ここから題材のサービスは以下の3つのデータを持っていることがわかる。

・7桁の郵便番号
・郵便番号が表現する住所（都道府県名、市区町村名、町域名）
・住所のカタカナ読み

2️⃣ データをリソースに分ける

このステップが実は大変難しい工程だが、これがうまくいくと残りの工程は成功したも同然らしい。

リソース：Web上に存在する名前のついた情報

では、題材のサービスで提供する情報はなんだろうか。

・郵便番号
ex. 112-0002は「東京都文京区小石川（トウキョウトブンキョウクコイシカワ）」という情報を持っている

・検索結果
ex. 112で検索すると東京都が表示されるみたいな（実際にそう成るかは知りません）

・地域
ex. 都道府県名、市区町村名、町域名から成る。

・スタート地点
クライアントがサービスを利用する時に最初にアクセスするリソース

まとめると

・郵便番号リソース
1つの郵便番号に対応する。その郵便番号の住所や読みも入っている。

・検索結果リソース
郵便番号や住所の一部で郵便番号を検索した結果。

・地域リソース
都道府県、市区町村、町域。上位の地域は下位の地域情報を含む。

・トップレベルリソース
Webサービスのスタート地点。都道府県リソースへのリンクと検索フォームを含む。

3️⃣ リソースにURIで名前をつける

郵便番号リソース
郵便番号112-0002のURIは

http://hogehoge.com/1120002
http://hogehoge.com/112-0002

以上、2通りが考えられる。（リンク先はNOT FOUNDになります）

前者はハイフンがないのでプログラム的に扱いやすく、短い
後者は人にとって読みやすい

というメリットがあるが、プログラムから扱いやすい方を正規のURIにした方が良いので前者を採用する。

検索結果リソース
検索キーワードの入力が必要。
以下は例

http://hogehoge.com/search?q=小石川

/searchは検索クエリを受け取るリソースのURIで、「q」が検索クエリを表現するクエリパラメータである。

実際はUTF-8で%エンコードするので以下のようになる

http://hogehoge.com/search?q=%E5%B0%hoge~~~

一部がパラメータとして変動する場合は「{」、「}」でパラメータを囲むのが一般的で、検索結果リソースのURIは以下になる。

http://hogehoge.com/search?q={query}

地域リソース
地域リソースは階層を持っており、都道府県の下には市区町村、その下には町域がある。

例えば、東京都、文京区、小石川は以下になる

http://hogehoge.com/東京都
http://hogehoge.com/東京都/文京区
http://hogehoge.com/東京都/文京区/小石川

地域リソースのURIは以下になる。

http://hogehoge.com/{都道府県}/{市区町村}/{町域}

トップレベルリソース
サービスのスタート地点なので、以下になる。
簡単😀

http://hogehoge.com

4️⃣ クライアントに提供するリソースの表現を設計する

代表的なリソースの表現形式はXML表現、軽量フォーマット表現、マルチメディア表現の3つ。

マルチメディア表現は画像や映像で表現するので、郵便番号を検索する今回の題材では不要。

前者2つの表現を利用する。

XML表現 

XML表現を選択する際の指針としては「独自フォーマットを作り出さないこと」。

XMLでは自由にタグを作れるが、既存フォーマットに不足があれば独自でタグを足して拡張できるのが真のメリットなので、まずは既存フォーマットを探してみるのがオススメのようだ。

参考書籍では、XML表現にXHTMLを採用している。

理由としては、

1️⃣ Atomを採用すると必須項目として著者や更新日時が必要だが、郵便番号データにはこれらがないから
2️⃣ ブラウザで表示するフォーマットを用意したいから

2️⃣は、Web APIの提供が主ではあるが、ブラウザで最低限表示できると便利だからXMLとHTMLの両者を統合できるXTHMLを採用したようです。

軽量フォーマット表現 

代表的なフォーマットとしてはJSON、YAML、CSVがある。
どれも聞いたことある💡

参考書籍では、JSONを採用している。

理由としては、

1️⃣ JavaScriptがメインのクライアントになる可能性が高いから
2️⃣ クロスブラウザ通信ができるJSONPを利用できるから

※XHTMLやJSONの実際の表現の例は書くと長くなって手と目が疲れるので、参考書籍を実際に手にしてご覧ください🙇‍♂️

↑と思ったらまとめてくれている記事ありました🙌

リソースの表現はURIで表現することもできる。

ex.) 112-0002という郵便番号リソースのURI

http://hogehoge.com/1120002.html（XHTML表現）
http://hogehoge.com/1120002.json（JSON表現）

5️⃣ リンクとフォームを利用してリソース同士を結びつける

設計してきたリソース同士をリンクで接続する。

ちなみに筆者が一番好きな工程らしい。
はて、、🤔
わからん笑

これのリソースの例も下記ページでまとめてくれているので参考になると思います。

検索結果リソース

「112」で検索した場合は112-xxxx系のリンクを配置して、ページネーションする場合は次ページのリンクも配置しようね〜ってイメージ

地域リソース

訪れたリンクが東京都の一覧であれば、その下位地域のリソースのリンクを配置しようね〜ってイメージ
ex.) 千代田区、文京区、小笠原村等のリンク

他は省略します。

リソース間のリンク関係は図示して相関関係をわかるようにしておくと、本来ここ繋げておかないとダメじゃね？とかがわかるようになるので図示しておくことをお勧めしていた。

地味にドキュメントを残すという観点でも大事だよな🤔

6️⃣ イベントの標準的なコースを検討する

基本的には3つのコースがある

郵便番号検索

フォームに郵便番号入力
👉 検索結果リソースを取得
👉 目的の郵便番号リソースを取得

住所から郵便番号を検索

フォームに住所入力
👉 検索結果リソースを取得（必要ならページをめくる）
👉 目的の郵便番号リソースを取得

地域リソースの階層をたどりながら郵便番号を検索

都道府県リソースを選択し、市区町村一覧を表示
👉 市区町村リソースを選択し、町域一覧を表示
👉 町域リソースを選択し、郵便番号一覧を表示
👉 目的の郵便番号リソースを取得

全てのやりとりはステートレスなので直接ブラウザのアドレス欄にURIを入力しても問題ない。

7️⃣ エラーについて検討する

エラーを返す場合にどのステータスコードを返すかを考えようという話。

存在しないURIを指定した

これはもう 404 NOT FOUND を返す。

必須パラメータを指定していない

クライアントの処理でパラメータが抜けている場合とかが該当する。
400 Bad Requestを返す。

こんなかんじ。

*
*
*

今回は読み取り専用のWebサービスの設計ケースについて学びました。

まず手を動かせばええやろという考えもありますが、サービスとして世の中に提供していくには設計をしっかりとすることも大事だなと、改めて思わされました。

URIの設計は実際にAPIを作るときとかに役に立つと思うので引き続きインプットしていく。

その後はもちろんアウトプットもするんや🔥

作りたいものも考えとこ🤔

次回は書き込みも可能編を予定してます👋