10分で理解する初めてのAPI

10分で理解する初めてのAPIとは

公開APIに興味を持っている人はどれくらいいるのか?にも書いたとおり、公開APIに興味を持っている人は少なからずいると思います。では、なぜ実際に公開APIを利用したサイトを作ってみないのかというと、公開APIを利用したサイトが完成するまでの流れにも書いたように、実際にサイトを作るまでにはいろいろな壁があるからです。
というわけで、今回は少しでも公開APIに対する抵抗感を取り除いてもらうために、「10分で理解する初めてのAPI」ページを作ってみました。「本当に10分で理解できるのか?」と疑問を持たれてしまいそうですが、「公開APIを利用するのは、怖い、難しい、大変なことではない」ということを理解していただけたら幸いです。サンプルソースとしてはPHP5を使わせてもらいましたが、基本的にはどのプログラミング(スクリプト)言語を用いても大丈夫なはずです。公開APIを利用したサイト作りへの第一歩としてこのページをご覧になってください。
このエントリーを含むはてなブックマーク

公開APIを選択 - お天気Webサービス

今回、公開APIとして取り上げたのは、livedoorの「お天気Webサービス」です。なぜこのAPIを選んだのかというと、

1. 日本のサービスで、日本語のみで理解できる
2. 何が出来るAPIなのかイメージしやすい
3. 会員登録しなくても利用できる
4. 開発用ドキュメントがHTMLでWeb上に公開されている
5. 他のAPIとのマッシュアップ用に利用しやすい

という理由からです。
他のどのAPIでもそうですが、「利用しやすい、イメージしやすい」APIであることはとても大切なことです。

サンプルサイトを作ってみる

サンプルサイトを作る前に、まずはお天気Webサービス仕様 - Weather Hacks - livedoor 天気情報を簡単にでも良いので読んでみてください。「リクエストパラメータ」「レスポンスフィールド」の解説と実際の「XMLデータサンプル」が載っています。
このAPIの仕様を確認したところで、試しにPHP5を利用してサンプルサイトを作ってみました。本来、天気を表示する地域はデータベースからユーザー情報の住所を設定したり、POSTやGETで入力された値を利用しますが、今回はサンプルということで固定値に設定しています。では、まずはできあがったサンプルサイトを見てください。「お天気Webサービス(REST)」を利用して、神奈川県横浜市の明日の天気と最高気温、最低気温を表示しています。

お天気Webサービスサンプル-ZAPAnet-

PHP5のサンプルソースコード

サンプルサイトを見た後は、次にサンプルソースを見てみましょう。
素人のPHPソースコードを見せてしまうのは、これ以上ないくらい恥ずかしいことですが、恥を忍んで公開してみることにします。

lwwssample.phps
(ブラウザ表示で文字化けしていた場合は、ブラウザ上でUnicode(UTF-8)にエンコードしてください)

PHP5のサンプルソースコード解説

上記ソースコード中にコメント文として解説も載せておきましたが、順を追ってもう一度解説したいと思います。

まず最初に、「サイト設定」の部分ですが、これはプログラムのロジックとデザインを分離させるために設定してあるだけですので、直接HTMLコードに書いても何の問題もありません。

//サイト設定(タイトル、URL、CSS、文字コード、サイト説明文などを設定します)
$site['title'] = "";
$site['url'] = "";
$site['css'] = "";
$site['mojicode'] = "";
$site['info'] = "";
$site['copyright'] = "";

続いて、XMLデータ取得用ベースURLの設定とリクエストパラメータの設定になります。
XMLデータ取得用ベースURLは、お天気Webサービス仕様ページに書かれている通りに設定します。REST APIではこのベースURLにパラメータを付加して通信を行います。パラメータもお天気Webサービス仕様ページに書かれている通り「city」「day」を設定します。パラメータが少ないので簡単でわかりやすいですね。

//XMLデータ取得用ベースURL
$req = "http://weather.livedoor.com/forecast/webservice/rest/v1";

//リクエストパラメータ設定(今回はサンプルとして固定値を設定しています)
$city = "70";
$day = "tomorrow";

//XMLデータ取得用リクエストURL生成
$req .= "?city=".$city."&day=".$day;

今回はサンプルとして、「横浜の明日の天気」を固定値で設定していますが、実際に利用する際はデータベースからユーザー情報の住所を設定したり、POSTやGETで入力された値を設定してください。
リクエスト用のURLが生成できたら、次は実際に通信を行ってXMLの解析を行います。PHP5であれば下記のようにPHP標準関数「simplexml_load_file」を使えば一行で終了します。

$xml = simplexml_load_file($req);

これだけでXMLの解析が終了し、$xmlオブジェクトにデータが格納されます。
$xmlオブジェクトにどのようにデータが格納されたかは、print_r($xml);部分のコメント文を外して、実際にオブジェクトの内容を表示して確認してみてください。ライブドアからREST APIで返ってきたXMLがどのように変換されたかがよくわかります。例えば、取得したXMLデータのタグ名"title"には、$xml->titleでアクセスできます。同様にタグ名"image"の"url"には、$xml->image->urlでアクセスすることが出来ます。

後は、自分の好きなようにHTMLを表示させれば完成です。
ここではサンプルソースとして、上記(テキストエリア内参照)のようにヒアドキュメントで一気にHTMLを表示していますが、この辺りは好みに合わせて自由に記述してください。

REST APIのまとめ

つまり、REST APIを使った公開APIは

1. リクエスト用のURLを生成する
2. 通信を行いXMLを解析する
3. 自分の好きなように表示させる

の3つの手順だけで利用できることがわかったと思います。
「何か難しそう…」というイメージから「自分にもできそうかも…!」と思っていただけたら幸いです。

Ajaxなどに対応させたオリジナルのサイトを作ってみる

このページでは、簡単にAPI利用方法について解説してきましたが、あとは少しずつ自分のアイディアを組み込んでいくことで自分だけのオリジナルサイトができあがります。例えば、上記サンプルコードでは横浜の明日の天気しか表示できませんでしたが、他の地域にも対応させてみると以下のようなサイトが作成できます。

お天気Webサービス-ZAPAnet-

「いつ」「どこの地域」の二つのパラメータをGETで渡して、PHP内で処理をして天気予報を表示させています。
次に、上記サイトをAjaxに対応させ、画面遷移なしに表示できるようにしてみると以下のようなサイトが作成できます。

お天気Webサービス(Ajax版)-ZAPAnet-

Ajaxを利用すると、画面遷移のないWebアプリを構築できるようになります(ただし、PHP以外にJavascriptの知識が必要になり、また動作はクライアントサイドに依存してしまうため、バグ取りなどもなかなか大変になってくる欠点もあります)。Ajaxを利用したり、他のAPIとのマッシュアップで今までにないサイト作りに是非チャレンジしてみてください。

最後に

今回は、「10分で理解する初めてのAPI」としてお天気Webサービスを扱いました。上記の通り、このAPIは参入障壁の少ないわかりやすいAPIです。まずはわかりやすいAPIに触れてみることで「公開APIに対する抵抗感」が取り除かれるのではないかと思い、このページを作りました。PHP5という限定された言語ではありましたが、「公開APIを利用したサイト作り」への第一歩の参考にしてもらえれば幸いです。
もし、他の言語でお天気Webサービスを利用したサンプルサイトとサンプルソースを公開された(もしくはこれから公開される)方がいましたら、下記ブログ記事(もしくはメールフォーム)までご連絡ください。こちらのページからリンクさせていただきたいと思います。また、上記サンプルソースコードでおかしな点や改善点がある場合にもご連絡ください。感想などもお待ちしています。
それでは、この辺で「10分で理解する初めてのAPI」は終了とします。「読んでるだけで10分越えたよ!」という方がいましたらごめんなさい。時間がかかった分だけ、公開APIに興味があるのだと思います。10分越えた時点できっと"理解した"のだと思います。

「10分で理解する初めてのAPI」BBS