前回は、JavaScriptの記法でデータを記述できる JSONについてまとめた。ここでは、郵便番号検索サービスの設計を通じて、読み取り専用Webサービスのリソース設計について説明する。
１ リソース設計とは
リソース設計とは、クライアントとサーバの間のインタフェースの設計、つまりWebサービスやWeb APIの外部設計である。どのようにリソースを分割し、URIで名前をつけ、相互にリンクを持たせるかが設計のポイントである。
設計とは、システムをどのような構成でどのように開発するのかを検討し、図や文書に残す作業である。リソースを設計する際に大切なことは、WebサービスとWeb APIを分けて考えないことである。
２ リソース指向アーキテクチャのアプローチ
リソース指向アーキテクチャ（Resource Oriented Architecture）の設計アプローチとは、以下の7つのステップからなる設計方法である（『RESTful Webサービス』推奨）。なお、RESTful Webサービスの性質として、アドレス可能性、ステートレス性、接続性、統一インタフェースの4つが挙げられている（Webのアーキテクチャスタイル（設計思想） REST参照）。
- Webサービスで提供するデータを特定する
- データをリソースに分ける
- リソースにURIで名前を付ける
- クライアントに提供するリソースの表現を設計する
- リンクとフォームを利用してリソース同士を結び付ける
- イベントの標準的なコースを検討する
- エラーについて検討する
３ 郵便番号検索サービスの設計
郵便番号検索サービスの要件は以下の4つである。
- 日本の郵便番号情報を提供する：郵便番号情報は、郵便番号、住所、住所の読みからなる。住所は、都道府県名、市区町村名、町域名からなる
- 郵便番号の前方一致で、郵便番号情報を検索できる
- 住所および住所の読みで、郵便番号情報を全文検索できる
- データはすべて読み取り専用である
４ Webサービスで提供するデータを特定する
リソース設計の最初の工程は、サービスで提供するデータを理解し特定する作業である。このサービスで提供するデータは、日本郵便が公開している郵便番号のCSVデータをもとにしている（http://www.post.japanpost.jp/zipcode/download.html）。ここから、このサービスは以下の3つのデータを持っていることがわかる。
- 7桁の郵便番号
- その郵便番号が表現する住所（都道府県名、市町村名、町域名）
- 住所のカタカナ読み
５ データをリソースに分ける
次に、データをリソースに分割する。リソースとは、Web上に存在する名前の付いた情報のことである。このWebサービスで提供するリソースをまとめると、以下の4種類がある。
- 郵便番号リソース：1つの郵便番号に対応するリソース。その郵便番号の住所や読みも入っている
- 検索結果リソース：郵便番号の一部や住所の一部で郵便番号を検索した結果のリソース
- 地域リソース：都道府県、市区町村、町域のリソース。上位の地域は、下位の地域の情報を含んでいる
- トップレベルリソース：このWebサービスのスタート地点。都道府県リソースへのリンクと、検索フォームを含んでいる
６ リソースにURIで名前を付ける
郵便番号リソース
郵便番号リソースは郵便番号で一意に識別できるので、URIには郵便番号を使うのが良いだろう。
検索結果リソース
検索結果リソースは検索キーワードの入力を必要とする。一般にクライアントからの入力を受け取る場合はクエリパラメータを利用する。検索キーワードを表現するクエリパラメータ名としては「q」がデファクトスタンダードになっている。
地域リソース
地域リソースは各都道府県や市区町村を表現するリソースである。地域リソースは階層を持っており、都道府県の下には市区町村が、市区町村の下には町域が存在する。その表現には「/」を利用する。
トップレベルリソース
トップレベルリソースはWebサービスのスタート地点である。このようなリソースには通常一番ルートとなるURIを与える。
７ クライアントに提供するリソースの表現を設計する
Web上の代表的な表現形式には以下の3つがある。
- XML表現：XHTML、Atom、独自XML
- 軽量フォーマット表現：JSON/JSONP、YAML、CSV
- マルチメディア表現：画像（GIF、JPEG、PNG）、映像（MPEG、WMV、MOV）、マルチページ画像（PDF、TIFF）
XML表現
XML表現を選択する際の重要な指針は、既存のフォーマットを探すことである。なぜならXMLは、あとからタグを足して拡張できるからである。以下の2つがある。
- XHTML：XHTMLは基本的な文書構造を持ち、リンクやフォームといったハイパーメディアで必要となる機能を一通り揃えている。ブラウザで表示できることも大きな特長。microformatsを用いると文書構造以上の意味を持たせることもできる
- Atom：Atomはブログや検索結果、ポッドキャストなどのリスト情報を表現するのに向いているフォーマットである。目的に応じてたような拡張が存在することも大きな特長。しかし、ID（<id>要素）、タイトル（<title>要素）、著者（<author>要素）、更新日時（<updated>要素）が必須なので、著者や更新日時を持たないデータには適用しづらい
今回はXML表現としてXHTMLを採用した。その理由は以下の2つ。郵便番号データには、Atomで必須の著者や更新日時がない。ブラウザで表示するフォーマットも用意したい。
軽量フォーマット表現
代表的な軽量フォーマット表現には、JSON、YAML（YAML Ain’t a Markup Language）、CSVがある。各フォーマットの利点と欠点は以下の通り。
- JSON：(○)JavaScriptとの相性がよい。配列やハッシュなどのデータ構造もある。(×)YAMLに比べると書きづらい
- YAML：(○)読みやすさ、書きやすさは一番。(×)ライブラリが比較的少ない
- CSV：(○)表形式のデータには最適。読み込み可能なソフトも多数存在。(×)文字コードの扱いに難あり。エスケープ文字問題もある
今回はJSONを選択した。これはJavaScriptがメインのクライアントになる可能性が高かったこと、クロスドメイン通信としてのJSONPがよいことが挙げられる。
URIで表現を指定する
郵便番号リソースと地域リソースでは、XHTML表現には「.html」、JSON表現には「.json」という拡張子を付ける。
８ リンクとフォームを利用してリソース同士を結び付ける
検索結果リソース
検索結果リソースは、特定のキーワードに合致する郵便番号と住所の一覧である。そのため、検索結果リソースから各郵便番号リソースへのリンクを張る必要がある。
地域リソース
地域リソースも検索結果リソースと同様である。その地域リソースが含む下位の地域リソースや郵便番号リソースにリンクする。
郵便番号リソース
郵便番号リソースは最終目的のリソースになるが、各地域のリソースへのリンクを入れておくことで、クライアントはそのURIを利用して別のアプリケーション状態に遷移できる。
トップレベルリソース
トップレベルリソースからは、Webサービスが提供するリソースへのリンクを用意する。地域リソースの一覧は、47都道府県一覧を入れるのが無難である。検索結果を生成するフォームは、qとtypeの2つの入力項目を使って動的に生成する。
リソース間のリンク関係
リソース間のリンク関係をまとめることで、孤立しているリソースの存在や、本来はリンクすべきリソースがリンクしていないなどのリンクの問題を把握しやすくなる。
９ イベントの標準的なコースを検討する
Webサービスの提供者側が想定する標準的な利用コースは、以下の3つである。
- 郵便番号を検索する
- 住所から郵便番号を検索する
- 地域リソースの階層をたどりながら郵便番号を選択するコース
10 エラーについて検討する
存在しないURIを指定した
存在しないURIを指定した場合、404 Not Foundを返す。
必須パラメータを指定していない
qというクエリパラメータが抜けてしまった場合、400 Bad Requestを返す。
サポートしないメソッドを使用した
GETとHEAD以外は受け付けないため、その場合405 Method Not Allowedを返す。
11 リソース設計のスキル
リソース設計はスキルであり、身につけることができる。URI設計方法、表現選択の指針、リンクの設計などはスキルの一部であるため、よく学ぶことが必要である。
最後に
リソース設計にあたっては『RESTful Webサービス』が提唱する7つのステップに基づいて実際の設計を行った。郵便番号検索はシンプルなWebサービスだが、URIによる名前付け、リソースの表現の選択、ハイパーリンクの活用など、様々なことを考慮する必要がある。しかし、リソース設計はスキルであるため、実践することで身につけることができる。
次回は、ブログやSNSなど、書き込み可能なWebサービスの設計についてまとめる。
 |
