2012年8月8日公開

※ PDF版はこちらです

復旧・復興支援データベースAPI改善提言書

目次

1. 本提言について

2. 提言の骨子

3. 現 API における問題点

4.「APIの運用について」の提言

5.「Web APIの形式について」の提言

5.1. JSON データ形式の採用

5.2. CORS (Cross-Origin Resource Sharing) への対応

5.3.レスポンス・データの区切りを統一・構造化

5.4. レスポンス・データ内の改行コードを統一

5.5. レスポンス・データを構造化

5.6. 実用的な検索

5.7. API リファレンスの改善

6.「提供するデータについて」の提言

6.1. 比較的に実現が可能と思われる要望

6.2. 各省庁、自治体の支援制度に関する要望

7.関連のリンク先

1. 本提言について

本提言は、復旧・復興支援データベース API を使用して、新たなサービスを開発する目的で開催されたイベント 「復旧・復興支援データベースAPIハッカソン」 で参加者から寄せられた意見をもとに、この API がより効果的に、より広く使われることを期待して作成されました。
「復旧・復興支援データベースAPIハッカソン」 は、経済産業省と三菱総合研究所、震災復興を継続的に支援するための IT 開発を支えるコミュニティ “Hack For Japan（ハック・フォー・ジャパン）” の三者により2012年6月2日に共同で開催されました。有志のソフトウェア開発者・行政書士・税理士などが集まり、経済産業省の方からはこのサイトの目的や使用状況などを、税理士の方からは支援制度の実際の利用状況をうかがった上で参加者全体でアイデアを出し、議論、開発へと進めていく実践的なイベントでした。

Hack For Japan は、ハッカソンでのAPI 利用経験をもとにした本提言によって、被災者・被災事業者への支援制度の情報がより効果的に使われ、これらの活動が官民一体となって展開されることを願います。

なお、本提言は以下の三点を対象としています。

• 復旧・復興支援制度データベース
  • http://www.r-assistance.go.jp/default.aspx
• 復旧・復興支援制度データベースAPI
  • http://www.r-assistance.go.jp/about_api.aspx
• 復旧・復興支援制度データベースAPIリファレンス
  • http://ssdbstorage.blob.core.windows.net/ssdb-apidoc/API-reference.html（リンク切れ：2015年3月1日現在、https://www.r-assistance.go.jp/blob/ssdb-apidoc/API-reference_v1.html に移行したことを確認）

2. 提言の骨子

復旧・復興支援制度データベースが提供しているWeb APIについて、「どのような改善を図れば、外部の開発者が利用しやすくなるか」という点を提言の骨子とします。提言内容は、改善点を多角的に示し、かつ着手可能なポイントを具体的に挙げ、優先度を設けています。関係省庁におかれましては、本提言で示される改善施策の中から、着手可能かつ優先度や効果が高いものから対応いただくことを期待します。

3. 現 API における問題点

復旧・復興支援データベースAPIの利用において、改善すべき問題点として挙げられた主たる内容は、優先度が高く、比較的対応も容易であろうと想定する順に挙げて以下の通りです。

1. APIの運用について
   • APIの仕様変更による利用者側への影響を考慮した運用がなされていない

2. Web APIの形式について
   • 提供されるデータ構造が一般的なWeb APIの形式に準じていないため使いにくい

3. 提供するデータについて
   • 復旧・復興支援データベース( http://www.r-assistance.go.jp/ )のシステム上での利用を想定した形でWeb APIが提供されていると推察され、本来は保持されているであろう有用なデータがAPIより取得できない

現在、bに関してはHack For Japan有志によるラッパーの開発により、大幅な改善が図られていますが、aの問題点が改善されない限り、根本的な問題の解決や利便性の向上には至らないという現状があります。その点を考慮の上、次項目からの改善提言をご一読ください。

4.「APIの運用について」の提言

問題点：APIの仕様変更による利用者側への影響を考慮した運用がなされていない

挙動に影響のある変更がWeb APIに加えられる場合には、利用者側のシステムに配慮し、十分な告知と改修期間が利用者側に必要です。あるいは仕様変更の発生したWeb APIを別のURLで新たに公開し、旧Web APIに関しても既存の利用者が移行に十分な時間を確保するまで継続して提供する、もしくは永続的に提供し続けるなどの運用が求められます。

新バージョンのWeb APIを用意する場合には、既存のレスポンスを維持しつつ新たなフィールドを追加する分には下位互換性が保たれるため、基本的に利用者側へ影響を与えることはなく、新たなフィールドの追加を利用者に向けて告知するだけで済みます。

先日、提供中のWeb APIに対して、利用者側への告知がない状態で仕様変更が加えられたため、復旧・復興支援データベースWeb APIを利用しているHack For Japan参加者らのシステムに対して不具合が発生する事態に至りました。これは参加者に限らず、全ての復旧・復興支援データベースWeb APIの利用者に対しても同様のことが発生していたと言えます。

現状のリファレンスにおいては更新情報のみ記載されており、これを防げる形での運用にはなっていません。

こうした状況を踏まえ、以下にWeb API提供企業の一般的な対応を参考として記載します。

1. Web APIの機能を停止する場合

• 機能停止の告知から2～6カ月ほどの期間を設けて停止させます。ただし、利用者の数が多く影響が大きな場合は年単位の移行期間を設ける場合もあり、Web APIが提供する機能内容や影響範囲など、API停止によって発生する影響度の大きさに応じて移行期間を定めます。
• 告知手段は提供サイト上のお知らせ、ブログ、登録されている利用者のメールアドレスに対してのメール配信、他あらゆる開発者向けのコミュニケーション手段（TwitterやFacebookページなど他企業のサービスも含む）を利用して告知します。

2. Web APIの仕様を変更する場合

• Web APIのレスポンスの仕様で提供されているフィールドが既存のものから内容が変わる場合は、機能停止の場合と同様の対応をその影響度に応じて実施します。
• Web APIのレスポンスに新たなフィールドを追加する場合、あるいは既存のフィールドに変更を加える場合でも、利用者側への影響にかかわらず、利用者に向けて告知を実施し、猶予期間を設けて変更を行います。

いずれの場合に関しても、現状は利用者側に周知するために有効な手段が既存の復旧・復興支援データベースAPIのサイト上に存在せず、利用者からのメールでの問い合わせという一方通行な手段のみが提供され、技術的な問い合わせの窓口がなく運用されています。

利用者への周知の面で、既存のサイト上でお知らせを掲載する場合も、支援制度自体のお知らせに掲載するのではなく、APIの内容を切り出したお知らせを用意し、それをRSSとしても提供するような形式が一般的です。

これを既存のサイト上で新たに構築しようとした場合、開発費用が新たにかかることも想定されます。そこで開発費用をかけずに復旧・復興支援データベースAPIを利用する開発者に向けての情報配信、コミュニケーション手段となりえる施策をいくつか以下に提案いたします。情報配信の手段、継続的なWeb APIの機能改善のフィードバックなどに活用できることが想定できますので導入を検討ください。

• Twitter
  • RSSのような形でお知らせだけを配信する手段としての利用から、API利用者とのコミュニケーションの手段として利用できます。コミュニケーションの手段としての利用では、即応性が得られやすいサービスです。匿名のアカウントで利用しているユーザも多いため、実際に何かしらのコミュニケーションを取る際には利用者の顔が見えない側面があります。
• Facebook
  • RSSのような形でお知らせだけを配信する手段としての利用から、API利用者とのコミュニケーションの手段として利用できます。実名での利用が多く、利用者の顔が見える特長があります。
• Google+
  • RSSのような形でお知らせだけを配信する手段から、イベントなどの連携、ビデオチャットであるHangoutといった、コミュニケーションの手段として利用できる機能が豊富に備わっています。
• GitHub
  • プログラムを公開する場として開発者の間で利用されているソーシャルコーディングサービスです。APIのレスポンスとなるスキーマファイルを公開したりすることで、利用者側からの改善の要望をPull Requestといった形で受けることが可能となり、継続的にフィードバックを受けて、より利用されるWeb APIに改善していけることが想定されます。

これらのコミュニケーション手段の導入により、現在は提供されていないWeb API利用者と運営側とのコミュニティを形成することが可能となります。ただし、複数のコミュニケーション手段を用意すると応対にかかるリソースがその分だけ増加するため、運用にかけるリソースの状況と狙う効果によって最適な選択をすることが重要です。

現状、Hack For JapanのFacebookグループ( https://www.facebook.com/groups/hack4jp/ )がそれに近いものとして機能していますが、Web APIにフォーカスした利用者のコミュニティが存在することで、利用者間でのWeb API利用上での問題解決や情報共有などが図られ、運営側の作業リソースを消費せずに利用が促進されます。

また、APIに不具合が発生している場合などの連絡手段、利用者側へのサポートとしても機能しますので、今以上のWeb APIの利用が促され、支援制度の情報を世に広げるサービスの誕生につながります。運営側に対応していくだけの十分な人的リソースが確保できない場合でも、民間ボランティアのコミュニティ管理人を募集し、運営のサポートをしてもらうような官民連携の運用も可能です。

5.「Web APIの形式について」の提言

問題点：提供されるデータ構造が一般的なWeb APIの形式に準じていないため使いにくい

復旧・復興支援制度データベースAPIのWeb APIとしての形式に関して、より簡易的に、開発者のアイデアに対して柔軟に、復旧・復興支援制度データベースAPIの利用を促進するために、以下の対応の実施を提言します。

本項では、特に「本 API を試し、使用する一般の Web 開発者を増やす」、「本 API を使用した Web サービスを増やす」という観点から改善点を挙げています。なお改善点を解決する際には、開発者の利用を促すために対応表を作成し、進捗状況を公開することを要請します。

補足となりますが Web API の提供にあっては、開発者が「簡単に試せること」、「試すための敷居が低いこと」が非常に重要です。開発者が簡単に試せる API は、結果的に多くの開発者を惹きつけ、その API を使用して本格的にサービスを作る開発者と、作られるサービスの増加につながります。

5.1. JSON データ形式の採用

• 現状:  XML 形式でレスポンスを返す仕様です。
• 課題:  XML は多くのプログラミング言語で扱いが煩雑で、ライブラリも使いづらいものが多いです。習熟した開発者が少なく、特に Web 開発者には不人気です。
• 改良案: JSON 形式の採用を提案します。 JSON はフォーマットが単純であることから、多くのプログラミング言語でシンプルなライブラリが実装されています。多くの Web 開発者が日常的に使用しています。
• 効果: 開発効率の向上、本 API を扱える開発者の増加、本 API を試す・使うモチベーションの向上
• 備考: JSON の採用にあたっては、下記 5.2. のように JSONP によって CORS アクセスできることが期待されます。

5.2. CORS (Cross-Origin Resource Sharing) への対応

• 現状: 指定 URL へのアクセスに対し単に XML データを返す仕様です。
• 課題: r-assistance.go.jp 以外の Web ページでは、ブラウザの JavaScript から本 API を直接呼び出すことができません。このため開発者は新サービスで本 API を使用するためにサーバーを用意しなければならず、開発・運用コストが増加します。これはほぼ全てのブラウザで採用されている同一生成元ポリシー (Same Origin Policy) によるものです。
• 改良案1: 5.1 の採用による JSONP の提供を提案します。
• 改良案2: XML 形式を維持する場合は Access-Control-Allow-Origin の適切な設定による XMLHttpRequest2 への対応を提案します。
• 効果: 開発効率の向上、新サービスの運用コストの削減、本 API を試す・使うモチベーションの向上

5.3.レスポンス・データの区切りを統一・構造化

• 現状: 本 API の中には、レスポンス・データ内で複数の要素を一つの文字列で表し、要素を区切るためにカンマ・パイプ文字・空白・改行・二重スラッシュなどを用いているものがあります。代表的な例が “IDs” です。
• 課題: 開発者は、本 API から XML レスポンスを受け取ってライブラリで XML の解釈をする処理を記述した後、レスポンスの構造を API ごとに把握し、さらに区切り文字の処理を自力で API に応じて記述しなければなりません。こうした無駄に複雑なデータ処理は、開発者が本 API の使用を敬遠する原因になります。これは、開発効率に影響するだけではなく、不具合・バグが混入する原因にもなるためです。
• 改良案1: 5.1 を採用し、その中で JSON の配列としてこのような複数要素のレスポンスを実装することを提案します。
• 改良案2: XML 形式を維持する場合は、カンマ区切り等ではなく XML のタグで区切ることでデータ列を表現するよう提案します。
  • XML 例: <IDs><id>86</id><id>103</id><id>110</id></IDs>
  • XML ではこのように冗長な表現になることも JSON (5.1) を提案する理由です。
• 効果: 開発効率の向上、本 API を試す・使うモチベーションの向上、本 API を使うサービスの質の向上
• 備考: 該当する API の例
  • searchSupportInformations
  • getSupportInformation
  • getSupportInformationNotifications

5.4. レスポンス・データ内の改行コードを統一

• 現状: レスポンス・データに複数行テキストが含まれる場合、改行コードとして「CR+LF」と「LFのみ」が混在する仕様です。
• 課題: 開発者は、両改行コードに対応するために処理を複雑化しなければなりません。これは 5.3 と同様に開発者が本 API の使用を敬遠し、不具合・バグが混入する原因となります。
  • 改良案: 改行コードを「CR+LF」か「LFのみ」のいずれかに統一し、仕様上で明記することを提案します。
  • 効果: 開発効率の向上、本 API を試す・使うモチベーションの向上、本 API を使うサービスの質の向上

5.5. レスポンス・データを構造化

• 現状: 「復旧・復興支援制度」サイト (http://www.r-assistance.go.jp/) の仕様が先にあり、このサイトのためだけに設計されたデータ構造を、そのまま API として提供していると推察されます。例えば getContactsText は「お問い合わせ先一覧」を自由記述のテキストとして返す仕様で、これは  http://www.r-assistance.go.jp/ で表示されるテキストそのものです。
• 課題: 開発者は http://www.r-assistance.go.jp/ 専用に作られたと思われるデータから、必要なデータを分析・再解釈・抽出するプログラムを作る必要があります。これは 5.3 と同様に多くの開発者を本 API から遠ざける大きな原因となります。 getContactsText の例は特に顕著で、開発者は自由記述のテキストから電話番号・FAX番号・住所などを推定するプログラムを作らなければなりません。これにはかなり高度で専門的な技術が要求され、本 API を使おうとする開発者の多くに対して深刻な障壁となります。
• 改良案: 必要なデータのみを構造化するように API を設計し直すことを提案します。また、「自由記述のテキスト」というデータ形式を可能な限り排除・限定することをあわせて提案します。
  • 例 (5.1: JSON の場合) :

    
{

    "企業立地課": { "tel": "0xx-xxx-1234", "purpose": "成長産業向け" },

    "産業創出課": { "tel": "0xx-yyy-2345", "address": "○県○市...", ... },

    "まちづくり課": { "tel": "0xx-zzz-3456", "fax": "0xx-zzz-3457" }

    }


  • この例で “purpose” は自由記述に近い形式となっています。これは「目的・対象」のような要素は、構造化するために可能性のある選択肢を列挙しなければならず、現実的ではないためです。このようなデータに対してのみ限定的に、可能な限り範囲を狭め、短い自由記述テキストを採用することは有効だと考えられます。
• 効果: 開発効率の大幅な向上、本 API を扱える開発者の増加、本 API を試す・使うモチベーションの向上、本 API では今まで出来なかったことができるようになる、本 API を使うサービスの質の向上
• 備考: 該当する API と概要
  • getContactsText: 連絡先の自由記述テキスト
  • 全 API: 不統一な日付のフォーマットを統一、または date 型へ変更

5.6. 実用的な検索

• 現状: リクエストで指定できるパラメータには限られたものしかなく、目的のデータを得るには、必要とされる以上にデータを得るしか方法がありません。例えば「現時点で有効な支援制度」のみを取得する方法がありません。
• 課題1: 開発者は新しいサービスに必要なデータを抽出するフィルターを自力で作る必要があります。こうした余分な要求は 5.3 でも述べたように、開発者が本 API を敬遠する原因となります。開発効率に影響し、不具合・バグが混入する原因にもなるためです。例えば「現時点で有効な支援制度」のデータを得るには、本 API で全ての支援制度を取得してから、現時点で有効な支援制度のみを選びなおすプログラムを開発者が作る必要があります。
• 課題2: さらに r-assistance.go.jp の運用コストも増加します。無駄なデータを送るために API 提供サーバーとネットワークのリソースを余分に使うことになるためです。
• 改良案: 実用的によく使われるフィルタリング・パラメータを推定し、いくつかの新しいパラメータを提供することを提案します。推定が必要なのは、可能性のある全てのフィルターの需要に対応することは難しいためです。有効と思われる推定方法として、検索条件の記録を分析し、利用率が高いものを選ぶことが挙げられます。
• 効果: 開発効率の向上、本 API を試す・使うモチベーションの向上、本 API 提供コストの削減
• 備考1: 需要が多いと思われるパラメータ
  • 現時点・ある時点でその制度が有効かどうか
• 備考2: 『6.「提供するデータについて」の提言』も参照

5.7. API リファレンスの改善

• 現状: HTML 化はされたものの、1ページの HTML にすべての API の仕様が直列で表記されており、 API ごとにアンカーリンクなどが設定されていません。また、サンプル・コードなどがほぼ全く提供されていません。各 API 単体の仕様表記には大きな問題はありません。
• 課題: リンクがないため、複数の API 間を行き来して確認しながら作業を進めようとしても、必要な API の記載にたどり着くのに時間と手間がかかります。また、サンプルコードなどがないため、使い始めるまでの敷居が非常に高くなっています。
• 改良案1: 特に複数の記述の行き来のしやすさという点を重視して、既存 Web API のリファレンス構成を参考にすることを提案します。これにより Web API を使う開発者の敷居を大きく下げられます。例えば以下のようなリファレンスをご参照ください。
• Google Developers: https://developers.google.com/?hl=ja
• Yahoo!デベロッパーネットワーク: http://developer.yahoo.co.jp/
• 楽天ウェブサービス: http://webservice.rakuten.co.jp/
• Twitter Developers: https://dev.twitter.com/
• Facebook Developers: https://developers.facebook.com/
• 改良案2: DocBook 形式の導入を提案します。 XML への変換作業が発生しますが、既存のドキュメント構成のままでもナビゲーションが自動生成されるため、改善につながります。
• 改良案3: 機能逆引きリファレンスの追加を提案します。これにより、開発者が使いたい具体的な機能にすぐにたどり着けるようになります。さらに逆引きリファレンスを整備する過程で仕様を機能面から考えなおすことになり、二次的な効果として API がより改善されることも期待できます。
• 改良案4: サンプル・コードなどの追加を提案します。サンプルがあれば、開発者がすぐに API を使い始められるようになります。

6.「提供するデータについて」の提言

問題点：復旧・復興支援データベース( http://www.r-assistance.go.jp/ )のシステム上での利用を想定した形でWeb APIが提供されていると推察され、本来は保持されているであろう有用なデータがAPIより取得できない

「今以上に復旧・復興支援データベースWeb APIの利用を促す」、「より効果的に支援制度を被災者や被災地域の事業者に届ける」、「APIの利用が促進された結果、さまざまな支援制度が可視化され、有効活用されることで国や自治体からの支援制度の増加を期待する」という観点から、復旧・復興支援データベースWeb APIが提供するデータとして以下に挙げる要望が実現されることを期待します。

なお、先日の「復旧・復興支援データベースAPIハッカソン」 の際に、本Web APIが各省庁・自治体を跨いだこれまでにない取り組みであるという説明を受け、各係省庁・自治体間での支援制度フォーマットの統一や各支援制度の利用状況の把握などには大きなハードルがあることも配慮し、実現が可能と見込まれる要望の中から優先度の高い順に提言します。

ただし、提供に際して大きなハードルがあったとしても、実現すれば高い効果が見込まれるであろう国の支援制度フォーマットの統一や支援制度の利用状況の可視化などは、将来的に導入が必要な要望として、その内容に関して記述します。

6.1. 比較的に実現が可能と思われる要望

• 終了した支援制度の区別ができる情報
  • 現状は申請期限(applicatipon_deadline)が存在しているが、ContentItem型としての提供となっており、その内容は実態としてフリーフォーマットとなってしまっているため、APIの利用としては表示に閉じた利用しかほぼできない状況となっています。これをdate型にし、「窓口へお問い合わせください」といった支援制度の場合とは分けたレスポンスにすることで、日時を指定した検索や終了した支援制度のフィルタリングなど、大幅に利便性が向上します。
  • 上述のdate型の準備に関しては、既存の支援制度情報の登録部の改修が必須であることから、既存のデータ登録の状況から判断可能であろうdate型の代替案として、支援制度が申請を受け付けているか否かの死活情報をboolean型などで返す形も合わせて提案します。
• 「窓口へお問い合わせください」の解決
  • レスポンスの内容が「窓口へお問い合わせください」となってしまう場合、APIの利用価値がほぼ無い状態となってしまいます。最低限の配慮として、窓口情報の可視化を実施することで申請者に対して窓口への誘導が可能となります。
  • 「お問い合わせ一覧」(http://bit.ly/MAoNqQ)に掲載される窓口情報をマスターのDBとして用意し、その中に緯度経度も含めた形での税務署などの情報、電話番号などの連絡先を持たせ、支援制度に紐づく問い合わせ先をAPIのレスポンスとして返します。開発者が制作したシステムで、利用者に対して問い合わせ窓口までを利用者の位置情報に紐づけて提案することで、利用者が自身の居住地域に合わせて支援制度を探す手間を省き、システム側から適切な支援制度を提案できます。
• 特定のイベントが発生したかどうかを判断できる情報の追加
  • 既存のmeta要素のupdate_kindに追加、更新情報が取得できますが、過去のものとの差分が取得できないため、システムの優位性を活かすような差分を表示といった機能が実現できません。
• 制度と制度の依存関係に関する情報の追加
  • 制度の依存関係に関する情報は、既存のContentItem型のBody要素で取得可能ですが、制度対象者と必要な制度との情報を別要素として切り出すことで、制度対象者や依存関係を軸とした検索が可能となり利便性が向上します。
• 申請期限（application_deadline）
  • 条件により複数の申請期限が定められている場合があります。条件と申請期限を複数要素として提供することで、データの利便性が向上します。
• エントリのアクセス記録（アクセス数・アクセス日時）
  • 復旧・復興支援制度情報サイト上での各支援制度へのPVを集計し、データベースで保持することで、現在最も注目を集めている支援制度、人気のある支援制度などの可視化につながります。

6.2. 各省庁、自治体の支援制度に関する要望

• 支援制度フォーマットの画一化
  • 支援制度のフォーマットを国として画一的なものを用意し、例外的な部分に関しては個別にすることで、基本情報の部分でAPIとしての利用価値が大幅に向上します。
• 制度に対する予算の可視化
  • 各支援制度に使われている予算が可視化されると、税金の有効活用を納税者に対して啓蒙することが可能となります。これにより支援制度がより意義のあるものとなります。
• 実際に申請された件数
  • 各支援制度に対する支援制度が可視化されると、要望の多い支援制度や人気のある支援制度など、提供する支援制度の費用対効果なども可視化され、より税金の有効活用につながります。
  • 上述の制度に関する予算も可視化されていた場合、申請された件数と紐づけることで、支援制度にかけた費用対効果も可視化されます。

7.関連のリンク先

「復旧・復興支援データベースAPIハッカソン」 レポート

http://blog.hack4.jp/2012/06/api.html

「復旧・復興支援データベースAPIハッカソン」での成果物

http://www.hack4.jp/RelatedInfo/rassist

この文書は、クリエイティブ・コモンズライセンスの下に提供されています。

著作者の表示・非営利・CCライセンス継承の条件に従い、この文書を再利用していただけます。