RESTfulWebサービス設計課題 #04 リソースの特定とURI

ちょっと間が空いてしまいましたが、４回目の今日は、前回作成したER図等を元にリソースの特定とURIの設計を進めたいと思います。

0. 前回までの目次
#01 最初の構想
#02 要求
#03 提供データの特定とER図


1. リソースを特定する
(1)西暦年リソース
西暦年で各国の年号情報を串刺しするというコンセプトからして、西暦年は外せないでしょう。１つの西暦年に対する各国元号年の情報を持たせます。
なお、持たせる情報の詳細は次回予定のリソース表現の検討で考えます(以下、同様)。

(2)検索結果リソース
検索は機能で情報ではないですが、検索結果は情報ですのでリソースとして扱います。元号名、元号名の読み、天皇名、及び天皇名の読みで元号情報を検索した結果の情報を持たせます。

(3)元号リソース
元号の情報を持たせます。

(4)時代・王朝別元号リソース
時代・王朝ごとの元号一覧を持たせます。

(5)地域・国別元号リソース
各国/地域ごとの時代・王朝・元号の一覧を持たせます。

(6)地域・国別西暦年リソース
最初は日本しかありませんが、他の国の対応後は国指定で元号を取得したくなりそうです。その時、(1)の西暦年リソースだと余分な情報も含まれてしまいますので、国も指定出来た方が良いかもしれないと思いました。

(7)トップレベルリソース
このWebサービスのスタート地点。西暦年の指定、地域・国別元号リソースへのリンク、検索フォームを持たせます。


2. リソースにURIで名前を付ける
仮にアプリケーションのURLを「http://gengo.appspot.com」とします。
(1)西暦年リソース
西暦年リソースは西暦年で一意に識別できるので、西暦年がそのまま使えそうです。例えば、1092年は「http://gengo.appspot.com/1192」です。「年」は付けないことにします。可読性に問題はないのでプログラムで扱い易くするためです。

(2)検索結果リソース
まず、「/search」を検索クエリを受け取るリソースのURLとします。問題は、クエリパラメータです。
(a)文字表現はどのように扱うべきか？
　(a1)元号名と天皇名の漢字表現をどうあつかうか？
　　UTF-8で%エンコードした漢字表現を、そのままURIに使用します。
　(a2)元号名の読みと天皇名の読みは、ひらがな/カタカナ/ローマ字？
　　和暦だけをターゲットにするのではなく、中国/朝鮮/ベトナムまで含めるとどうすべきかちょっと悩むところです。ローマ字表記も各国ごとにばらばらで、いろいろな方式があるためどうしたものかと。
各国/地域の表音文字表現は下記の通りです。

• 日本：ひらがな、かたかな、ローマ字
• 朝鮮：ハングル、ハングルのローマ字表記
• 中国：ピンイン（ローマ字表記）
• 越南：クォック・グー（ローマ字表記）

中国やベトナムのように独自の表音文字がない(？、よくわかりません)ケースを考えると、ローマ字表記での統一が良さそうですが、実際にはアクセント記号も込みのため、単純にアスキー文字列で表現できるわけではありません。日本人ユーザーによる入力のし易さから考えて、今回は日本用には「ひらがな」(UTF-8の%エンコード)を採用することにします。つまり、ローマ字による表現の統一は諦めるため、読みによる串刺し検索ができなくなります。但し需要があるとは思えないので良しとしました。
その他の国は機能拡張時の検討事項として残しておきます。

(b)名前検索と読み検索とで検索結果リソースを区別すべきか？
名前は漢字で、読みはその他の文字になるため、使う側としては名前と読みとをことさら意識しないと思われます。ルールは分けないで同じ仕組みでのリソースとします。

(c)元号検索と天皇検索とで検索を区別すべきか？
リソース表現を工夫することで対応出来そうな気がしますので、一旦は区別せずに進めます。但し、天皇名は最初の機能からは落とすつもりですので、機能追加時には再検討を行います。ということで、クエリパラメータは慣例に合わせて「q」とします。

(d)地域・国別に検索したい場合はどう扱うか？
串刺しをデフォルトとし、国・地域別は階層を落として分けましょう。国/地域はUTF-8の%エンコーディングでは可読性が落ちるため英語表記とします。
「japan」「china」「korea」「vietnam」
なお、串刺しでの読み検索は、ローマ字表記を諦めたので、地域・国を省略できるということ以外にはあまり意味はなくなります。
まとめると、URIは以下のような感じです。

• 串刺し：「http://gengo.appspot.com/search?q=建」
• 日本　：「http://gengo.appspot.com/japan/search?q=建」
• 　　　　「http://gengo.appspot.com/japan/search?q=けん」
• 中国　：「http://gengo.appspot.com/china/search?q=建」
• 朝鮮　：「http://gengo.appspot.com/korea/search?q=建」
• 越南　：「http://gengo.appspot.com/vietnam/search?q=建」

(3)元号リソース
同じように考えます。但し、時代・王朝名と元号でのリソース重複を防止するため「gengo」を挟みます。元号と地域・国では、地域国を上位概念とします。理由は、使うときに「建長の日本」ではなく「日本の建長」で探すことの方が多いと思うからです。串刺しについては、各国が中国の元号をまねて付けたものもなくはないため、もしかしたら良い結果を産むかもしれません。

• 串刺し：「http://gengo.appspot.com/gengo/建長」
• 日本　：「http://gengo.appspot.com/japan/gengo/建長」
• 中国　：「http://gengo.appspot.com/china/gengo/建長」
• 朝鮮　：「http://gengo.appspot.com/korea/gengo/建長」
• 越南　：「http://gengo.appspot.com/vietnam/gengo/建長」

(4)時代・王朝別元号リソース
串刺しの情報は存在しません。「時代・王朝」は「era」として、それ以外は元号リソースと同様です。なお「＊＊時代」の「時代」は冗長なため含めないことにします。

• 串刺し：なし
• 日本　：「http://gengo.appspot.com/japan/era/鎌倉」
• 中国　：「http://gengo.appspot.com/china/era/明」
• 朝鮮　：「http://gengo.appspot.com/korea/era/李氏朝鮮」
• 越南　：「http://gengo.appspot.com/vietnam/era/阮朝」

(5)地域・国別元号リソース
同様に

• 日本　：「http://gengo.appspot.com/japan」
• 中国　：「http://gengo.appspot.com/china」
• 朝鮮　：「http://gengo.appspot.com/korea」
• 越南　：「http://gengo.appspot.com/vietnam」

(6)地域・国別西暦年リソース
「(1)西暦年リソース」の下位データと考えて

• 日本　：「http://gengo.appspot.com/1192/japan」
• 中国　：「http://gengo.appspot.com/1192/china」
• 朝鮮　：「http://gengo.appspot.com/1192/korea」
• 越南　：「http://gengo.appspot.com/1192/vietnam」

但し、例えば「http://gengo.appspot.com/japan/1192」のように西暦と地域・国の逆順は代理リソースとして、「301 Moved Permanently」で上記URIにリダイレクトします。

(7)トップレベルリソース
「http://gengo.appspot.com」


ここまで考えると、「(3)元号リソース」は串刺し用と地域・国別元号用とに分離した方がすっきりしそうですね。リソースの表記順も順番をかえた方が分かり易そうですし。まあ、正式なURIの仕様書は動くものができてからきちんと整備することにして、こんな感じで進めていきます。

あ〜、今日も文字ばっかりでした。

RESTfulWebサービス設計課題 和暦検索 #03 提供データの特定とER図

RESTfulWebサービスの第３回目は、提供データの特定とER図の作成です。

本題のリソース設計に入る前に、サービスとして提供するデータを特定します。提供するデータは要求でかなり明らかになっていますが、構造化されていないため何をリソースとして管理すべきか分かりません。
そこでまずは、必要なデータをRDBのテーブル設計の要領でER図に落としてみました。それが下図です。（「astah*」のクラス図を使って作成したためプライマリキー(PK)が表現できていませんが、「テーブル名ID」がPKです。）

1. 説明

(1)南北朝の問題は「時代・王朝」を提供データとして設けることによって対応

南北朝や大覚寺統/亀山統の解決方法に悩みましたが、要求中には明示されていなかった「時代・王朝」を設けることで対応しました。これにより日本の平安時代の年号一覧などの機能(要求にはありませんでしたが)にも対応可能になります。

また、他の国/地域の王朝も区別できるようになります。特に中国では複数の王朝で同じ元号(「建武」など)が使用されることもあったようで、区別が容易になります。

(2)４カ国・地域共通データと日本独自データに分割

「時代・王朝」は共通データとして「元号」から参照しています。しかし「天皇」は日本独自データとして、天皇と元号を紐付けるデータを別途持たせるようにしました。

最初は「天皇」を「皇帝・天皇・国王」のように読み替えて「元号」と「時代・王朝」の間に挟むことも考えました。そうすれば、全て共通のデータ構造になるからです。

しかし

・日本の場合「将軍」や「総理大臣」という軸も考えられてなかなか複雑であること

・基本的には天皇の交代時に改元されがもし例外があった場合の処理が複雑になること

・中国/朝鮮半島/ベトナムの元号の詳細が勉強不足で分かっていないこと

・メインコンセプトである「西暦による各国元号の串刺し」には直接関係しないこと

から、断念しました。

2. 主な問題点と変更点

(1)２時代に跨がる元号の存在

実は「時代・王朝」の対応には、問題がありました。

日本では１つの元号が２つの時代に跨がることがあり、例えば「延暦」は西暦782年〜806年のため奈良時代と平安時代の両方に属します。少し複雑になりますが、「元号」のデータを２時代分重複してもつことで対応可能なので、正規化して「元号_時代・王朝」を設けました。

(2)「西暦」を削除

西暦ID = 西暦 で問題なさそうなので、「西暦」を作ったのはちょっとやり過ぎでした。

（が、下図のように消してから気が付きましたが、リソース設計用のデータ構造を示すだけなのでの残しておいた方が良かったように思えます。）

ということで変更後のER図を以下に示します。

3. 課題

(1)正規化し過ぎ

このER図は、リソース設計を行うためのデータの構造化として作成しました。

CRUDのうち基本的に使用するのは「C」と「R」のみで、しかも「C」を行うのは管理者のみであることを考えると、ほとんどの処理は「R」で、管理者がたまに簡単な「C」と「R」を行うのみであることを考えると(2012/01/09修正。改元時に終期の「U」があることの考慮もれ)、ここまでの正規化は行き過ぎかもしれません。

また現状では、RDBではなくGAEのBigTableに載せることを考えています。「元号年」のデータ数は多く見ても１万件程度のオーダーですので、ごりごりテーブルを結合させても大丈夫かと思いますが、詳細設計の段階では正規化を崩すことの検討も必要です。

(2)歴史学上の議論

元号、王朝、時代、その他諸々、今回のアプリで扱うデータの値にはいろいろ議論のあるところです。いくつかバリエーションを持たせることも不可能ではありませんが、ここでは何かひとつ決めうちで対応することにします。

たとえば「元号の読み」ですが、明治以前は明示されていないため複数の読み方が成立します。しかし今回は複数の読は対応せず、私の独断と偏見で読みを１つに絞らせて頂きます。

4. 要求の再確認

要求を上から順番に確認し、実現できないものないことを確認して本日は終了です。

○1. 機能要求

　○1-1. 西暦から和暦を知りたい(例：西暦2012年 -> 平成24年)

　　○1-1-1. 西暦に対応する和暦が存在しない場合は、その旨を教えて欲しい

　　○1-1-2. 西暦に対応する和暦が複数存在する場合

　　　○1-1-2-1. 改元の場合は、改元月日と併せて全和暦を表示して欲しい

　　　○1-1-2-2. 南北朝期の場合は、南朝/北朝両方の和暦を表示して欲しい

　○1-2. 和暦から西暦を知りたい(例：平成24年 -> 西暦2012年)

　○1-3. 元号から和暦情報を知りたい

　　○1-3-1. 和暦情報としては少なくとも以下の項目が欲しい

　　　　　　元号名、元号名の読み、元号の年数、始期(年月日)、終期(年月日)、天皇名、天皇名の読み

　　○1-3-2. 元号名の部分一致で和暦情報を検索したい

　　○1-3-3. 元号名の読みの部分一致で和暦情報を検索したい

　○1-4. 天皇から和暦情報を知りたい

　　○1-4-1. 天皇名で和暦情報を部分一致検索したい

　　○1-4-2. 天皇名の読みで和暦情報を部分一致検索したい

　○1-5. 他アプリへのサービス提供を可能とするためJSON形式のデータが欲しい

　○1-6. もちろん人間の読みやすい形でのデータも欲しい

○2.非機能要求

　○2-1. 他の元号使用国(中国、ベトナム、朝鮮半島)用機能の追加が容易な設計にして欲しい

　○2-2. 機密情報は扱わず、ユーザー管理も行わないのでセキュリティに配慮する必要はない

以上、お疲れさまでした。

RESTfulWebサービス設計課題 和暦検索 #02 要求

とりあえず、和暦検索サービスの要求をざっくりと考えてみました。

1. 機能要求

　1-1. 西暦から和暦を知りたい(例：西暦2012年 -> 平成24年)

　　1-1-1. 西暦に対応する和暦が存在しない場合は、その旨を教えて欲しい

　　1-1-2. 西暦に対応する和暦が複数存在する場合

　　　1-1-2-1. 改元の場合は、改元月日と併せて全和暦を表示して欲しい

　　　1-1-2-2. 南北朝期の場合は、南朝/北朝両方の和暦を表示して欲しい

　1-2. 和暦から西暦を知りたい(例：平成24年 -> 西暦2012年)

　1-3. 元号から和暦情報を知りたい

　　1-3-1. 和暦情報としては少なくとも以下の項目が欲しい

　　　　　　　　　　元号名、元号名の読み、元号の年数、始期(年月日)、終期(年月日)、天皇名、天皇名の読み

　　1-3-2. 元号名の部分一致で和暦情報を検索したい

　　1-3-3. 元号名の読みの部分一致で和暦情報を検索したい

　1-4. 天皇から和暦情報を知りたい

　　1-4-1. 天皇名で和暦情報を部分一致検索したい

　　1-4-2. 天皇名の読みで和暦情報を部分一致検索したい

　1-5. 他アプリへのサービス提供を可能とするためJSON形式のデータが欲しい

　1-6. もちろん人間の読みやすい形でのデータも欲しい

2.非機能要求

　2-1. 他の元号使用国(中国、ベトナム、朝鮮半島)用機能の追加が容易な設計にして欲しい

　2-2. 機密情報は扱わず、ユーザー管理も行わないのでセキュリティに配慮する必要はない

不足はあるでしょうが、まずはこんなところかと。

1-4の天皇による検索は、最初の開発からは落としてもよさそうです。

2-1の他の元号使用国用サービスについては、下の図のように各国元号を西暦で串刺しできると良さそうな感じです。いろいろと面倒なうえ、この記事のタイトルも和暦検索としてしまっているので多分作りませんが、URIの設計等では配慮しておきたいところです。

RESTfulWebサービス設計課題 和暦検索 #01 最初の構想

「Webを支える技術 -HTTP、URI、HTML、そしてREST」山本陽平(技術評論社 WEB+DB PRESS plus) を読んで、RESTfulなWebサービスのリソース設計を自分でもやってみようと
思い立ちました。

とはいえ、本に記載されている郵便番号検索サービスをまねして作ってみるだけでは全く芸がないので、和暦検索サービスを考えてみたいと思います。中期連載(?)になるかと思いますので、のんびりとお付き合い願います。

ということで、まずは簡単に構想を練ってみます。
Googleを検索すると、既にいろいろと和暦<->西暦の検索あるいは変換サービスがあるようです。

• 「世界帝王辞典」の西暦・和暦変換
• 「All about Japanese Study」の日本元号検索

しかしこれらのサイトでは、RESTで最も重要なアドレス可能性(※)が実現されていません。
実はWikipedeaでは

• http://ja.wikipedia.org/wiki/645年
• http://en.wikipedia.org/wiki/645
• http://ja.wikipedia.org/wiki/大化

の形で、アドレス可能性が実現されています。しかし、和暦->西暦への変換は元号の後の年を指定できませんし、基本的には人間が読むことを想定したフォーマットでしか提供されておらず、JSONP等でマッシュアップし易いサービスとはなっていません。

なお、和暦には

• １年の中で複数の元号が存在する(昭和64年と平成元年など)
• 南北朝時代には２系統の元号が存在する
• 元号の読みに同音が存在する(URIにローマ字表記を単純には使用できない)
• 未来の元号が不明(西暦2050年は平成で良いのか？など)

等の適度な(?)設計上の課題も存在するので、トレーニングとして丁度良さそうです。
また、過去分のデータは確定しているので最初は読み取り専用のサービスとして設計できるという利点もあります。

ということで、最初の構想の結論としての方針です。

• RESTを満たす和暦検索Webサービスを作ってみる
• 主眼はWebサービスの(リソース)設計を学習とする
• 見た目、実装、デプロイはできるだけ簡易に済ます(多分GAE Python)
• コンピュータが使いやすい形式でも提供する(Wikipediaや他サイトとの差別化)

(※)アドレス可能性
　URIでリソースを一意に特定可能であること。Wikipediaの例のようにアドレスで特定の情報が指定できることです。例に挙げた和暦検索サービスはそのような構造にはなっておらず、どの検索結果でも同じURIが割り振られています。

ブラウザがOSを抽象化する~アプリケーションソフトウェアの標準はWebアプリ~

明けましておめでとうございます。
新年ということもあり(?)、各所で言われていることですが、HTML5対応Webブラウザのインパクトを、再確認もかねてざっくり自分の表現でまとめてみました。

---
かつて、オペレーティングシステム(OS)によってハードウェアが抽象化されました。

いまや、HTML5(+JavaScript+CSS3)対応のWebブラウザが、クライアントマシン(のOS)を抽象化し、HTTP対応のWebServerは、サーバーマシンとその機能をクラウドOS(+ミドルウェア)として抽象化しています。

大抵のアプリケーションソフトウェアは、できるだけ多くのユーザーに使ってもらうことを願って作られるものです。従って、HTML5によるWebアプリとするのがデフォルトの選択肢となります。

補足１
　Webアプリをサーバーマシンが提供するアプリとみることも可能ですが、ここでは以下のように考えています。
　　(1)サーバーマシンが提供する機能
　　　・HTML/JavaScript/画像ファイルなどを格納するファイルシステム(OS)
　　　・データベースとそのアクセサ(ミドルウェア)
　　　・その他便利機能の提供(OS or ミドルウェア)
　　(2)クライアントマシンが実行する機能
　　　・サーバーの機能を用いて、ユーザーにアプリケーションの機能を提供する
補足２
　以上から(?)導かれるWebアプリを作るときの注意点は以下２点となることでしょう(天気予報風)。
　　・可能であれば、既に提供されている機能を利用(マッシュアップ)すること
　　・便利機能として他のアプリから利用しやすいようにインターフェースを設計すること