APIヘルスチェックのススメ: API Health

これはEnterprise APIs Advent Calendar 2015の12/20のエントリです。（このブログ、ここ数年年末のアドベントカレンダー用のエントリしかない…^^;）

一般向けであれ、特定パートナー向けであれ、Web APIの運用にはサービス監視が重要です。そして、サーバサイドにおける内部的な監視も大切ですが、API利用者に正しくサービスが提供できていることを確認するためには、クライアントから実際にリクエストを送る形態のヘルスチェックは欠かせません。

ApigeeのAPI Healthは、このクライアント視点のAPIヘルスチェックを簡単に実現する独立したサービスです。2015年12月現在、ベータ版で提供されており誰でも無料で利用できます。インターネットからアクセス可能ならどんなAPIでも監視対象にすることができます。あらかじめ定義したリクエストを指定した頻度で送信して、エラーの発生やレスポンスタイムの異常があればメールやSlackなどでアラートを送ってくれます。リクエストは世界４地点から送信することが可能で、成功率やレスポンスタイムを発信地点ごとにグラフ表示することなどもできます。

使い方は次の通り（詳細は公式ドキュメントを参照）：

  1. (もしまだ持っていなければ)Apigeeアカウントを用意する
  2. API Healthダッシュボードにログイン
  3. 左サイドの"+"、または右上の"Add Prove"ボタンでプローブを作成
    • プローブ名とステップ名をつける。プローブは1個以上のステップ（API呼び出し）からなるヘルスチェックの単位。単一のGETリクエストでもいいし、認証トークンを取得してそれを使うような一連の呼び出しシーケンスでもよい
    • ステップのリクエストURIとメソッド、期待するレスポンスコードを設定
    • "Show Advanced"を使うと、呼び出し前に短いスクリプトを実行したり、リクエストのヘッダを設定したりできる。また、レスポンスヘッダやJSONボディの一部を抽出して変数に設定することも可能（アサーションに使ったり次以降のステップで参照できる）
    • 必要なら"Add new step"でステップを追加
  4. プローブの動作を設定
    • チェック頻度: 30秒/1分/5分/15分/30分/1時間のいずれか
    • アラート条件: レスポンスコードや変数のアサーション失敗回数、レスポンスタイムが閾値を超えた回数、異常な遅延
    • 通知先: メール、HipChat、Slack
  5. リクエストの発信地を設定（以下の４地点をon/off）

最後に"I'm Done"を押せば定期ヘルスチェックが始まり、設定した条件でアラートを受けたり、ダッシュボードでこれまでのヘルスチェックの結果を参照することができます。

簡単に設定できる便利な無料サービスですので、監視したいAPIがあるすべての方にオススメです。ぜひお試しあれ！

SlackのWebHookとNTTドコモの雑談対話APIとApigeeで雑談ボットをつくる #apijp

Web API Advent Calendar 2014、最終日のエントリは、最近一部で流行中のチームコミュニケーションツールSlackのネタです。


（完成したボットをSlackで試しているところ）

Slackネタはid:i2keyさんの12/13の素敵なエントリ：
ZapierでSlackを佐野ひなこちゃんで埋め尽くす #apijp - @i2key のBlog
ですでに使われてしまいましたが、ここではSlackが提供する別のインテグレーション方法を使って雑談ボットを作ってみます。

Slackには外部プログラムとのさまざまなインテグレーション方法が用意されています。この中のOutgoing WebHooksの機能は、Slackに新しいメッセージが入力されるたびに設定した外部URLを呼び出してくれるというものです。これに、先日のAPI Meetup Tokyo #4でドコモさんが紹介していた雑談対話APIを組み合わせます。

SlackのWebHook呼び出しと雑談対話APIの呼び出し形式は異なるため、間でその調整や変換を行う何かが必要になります。通常なら何らかのスクリプトなどを書くところですが、ここではさりげない(?)宣伝を兼ねてApigee EdgeのAPI Proxyの機能を使ってこの接続を実現してみました。

おおまかな処理の流れ


  1. 指定された条件に合致するメッセージが入力されると、設定しておいたApigee ProxyのURLにSlackがメッセージテキストなどをPOSTする
  2. Apigeeがフォームデータを受け取り、メッセージテキスト(text)やユーザ名(user_name)などを取り出す
  3. ユーザ名が"slackbot"の場合、発言者は（自分を含む）ボットなので何もせず200で空のレスポンスを返して処理を終える。これを行わないと自分の発言に対してもWebHook呼び出しが起こるため無限ループが発生する（1回やらかしました）
  4. 以前の会話のコンテキストIDがキャッシュにあれば読み出す
  5. 必要なデータをJSON形式にしてドコモAPIにPOSTする
  6. ドコモAPIが返すJSONデータを受け取り、ボットの発言(utt)やコンテキストID(context)を取り出す
  7. コンテキストIDはSlackのchannel_idをキーとしてキャッシュに保存しておく
  8. ボットの発言をWebHookの返信形式のJSONにまとめ直してSlackに返す

Apigeeでの実装

これらはクラウド型のApigee無償版ですべて実現できます。


（ボット開発中のApigee画面）

Apigeeでの実装上のポイントは以下の通り：

  • SlackからPOSTされるフォームデータや、ドコモAPIから返されるJSON内データからのパラメタの取得にはExtractVariablesポリシーを使う
  • ドコモAPIへのリクエストや、Slackへのレスポンスの作成にはAssignMessageポリシーを使う
  • contextの保存・読み出しにはPopulateCacheポリシーとLookupCacheポリシーを使う
  • ボット発言による無限ループを防ぐためにはConditional FlowとRaiseFaultポリシーを使う

（「ポリシー」というのはApigee用語であらかじめ用意された処理部品のこと）

まとめ

Slackに限らず、最近はさまざまなサービスでWebHookが提供されるようになってきています。Apigeeの持つインタフェース変換機能を使えば、自分でPOSTを受けるサーバやスクリプトを用意することなく、さまざまな別のAPIに接続することができます。（ここでは扱いませんでしたが複数APIのマッシュアップも可能）

Apigeeは本来API提供者にAPI管理レイヤを提供するもので、ここに書いたツール的な用法は本質的な使い方ではありません。しかしWebHook用の接続ツールとしては特に有用性が高いかもしれないと感じました。

ちなみに書いている途中で、非常によく似た内容のブログ記事を見つけたので、本エントリのタイトルは敬意を表してこちらにあわせてみました。:-)
Safx: TypetalkのWebhookとNTTドコモの雑談対話APIとGoogle Apps Scriptで雑談ボットをつくる

SlackではなくnulabさんのTypetalk、ApigeeではなくGoogle Apps Scriptを使われていますが、仕組み的にはほとんど同じです。一部参考にさせていただきました、感謝！

apibでコマンドラインからAPIを負荷テスト #apijp

これはWeb API Advent Calendar 2014、8日目のエントリです。ツールの小ネタ第二弾です。

APIのテストには、目的に応じてcurlコマンドやPostman、そしてJMeterやab(Apache Bench)などさまざまなツールを使います。今回はabによく似た（そしてより進化した）シンプルなコマンドランベースの負荷・性能テストツールであるapib(API Bench)を紹介します。

特徴

  • keep-aliveã‚„chunked encodingを含む、HTTP 1.1の正確なサポート
  • 複数のI/Oスレッドを使いマルチコアを活用
  • 大きなオブジェクトのPOSTã‚„PUTをサポート
  • OAuth 1.0の署名をサポート
  • 実行結果はファイル出力可能（自動化のための連携が容易）

など。

インストール

MacならHomebrewで一発です：

brew install apib

それ以外のプラットフォームではGitHubからソースを取得してビルドする必要があります。

実行例

同時接続数10で30秒間、連続で目一杯リクエストを送る：

$ apib -c 10 -d 30 <ターゲットURL>
(5 / 30) 51.958 0% cpu
(10 / 30) 54.582 0% cpu
(15 / 30) 54.378 0% cpu
(20 / 30) 54.787 0% cpu
(25 / 30) 54.577 0% cpu
(30 / 30) 54.387 0% cpu
Duration:             30.012 seconds
Attempted requests:   1624
Successful requests:  1624
Non-200 results:      0
Connections opened:   10
Socket errors:        0

Throughput:           54.111 requests/second
Average latency:      184.049 milliseconds
Minimum latency:      175.175 milliseconds
Maximum latency:      384.165 milliseconds
Latency std. dev:     15.330 milliseconds
50% latency:          181.145 milliseconds
90% latency:          190.309 milliseconds
98% latency:          192.284 milliseconds
99% latency:          192.580 milliseconds

Client CPU average:    0%
Client CPU max:        0%
Client memory usage:    0%

Total bytes sent:      0.13 megabytes
Total bytes received:  0.17 megabytes
Send bandwidth:        0.03 megabits / second
Receive bandwidth:     0.05 megabits / second

apibにはメソッドやヘッダの指定、認証設定など他にも多くのオプションがあります。詳しくは、apib -hでヘルプを見たり、こちらを参照してください。

注意！

かんたんに大量のトラフィックを生成しますので、ターゲットはくれぐれも慎重に選んでください（通常は自分で開発・管理しているサーバ）。うかつに他人のサーバに負荷をかけると攻撃とみなされることがあります！

らくらくシーケンス図：WebSequenceDiagrams #apijp

これはWeb API Advent Calendar 2014、7日目のエントリです。知っている方も多いと思いますが、ツールの小ネタで。

Web APIを扱っていると、認証やマッシュアップのフローの記述など、簡単なシーケンス図を書きたくなる場合がよくあります。こんなときにオススメなのが、カナダのHanov Solutions社が提供する便利なWebサービスWebSequenceDiagrams。

次のようなシンプルなテキストを書くだけで：

title GWでのmashup

アプリ->GW: POST 郵便番号
GW->サービスA: GET /郵便番号
サービスA->GW: 住所(JSON)
GW->サービスB: POST 住所
サービスB->GW: 緯度経度(XML)
GW->アプリ: 緯度経度(JSON)

次のようなイメージを生成してくれます：

基本的に無償で使えますし、生成した図は直接リンクして使うこともPNGイメージとしてexportすることもできて非常に便利です。スタイルもいくつか用意されています。例：

ちゃんとAPIも用意されているので他のツールや言語と組み合わせるのも簡単。有償のプレミアム版では図の編集に追従するリンクの生成、より高度な記法やPDF/SVGでのexportなどもサポートされます。

シンプルですが非常に使い勝手の良いツールで、あなたのAPIツール箱にそろえておきたい優れものの一つです。

REST APIを記述せよ！Swagger紹介 #apijp

Web API Advent Calendar 2014、初日はSwaggerを紹介します。

SwaggerはReverbによって開発された、RestfulなAPIを記述する標準仕様です。APIを機械可読な形で記述することは、ドキュメント生成やツール開発、さまざまな形での自動化に非常に重要です。好き嫌いはともかく、SOAPにはWSDLという統一標準がありましたが、RESTには本質的にそういった標準がないため、類似するさまざまな仕様が開発されてきました。Swaggerはその中でも最も有望なものの一つだと思います。

1. 特徴

  • 記述はJSONでシンプル。ミニマム定義の例：
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "petstore"
    },
    "paths": {
        "/users": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Describe the 200 response in more detail"
                    }
                }
            }
        }
    }
}

Swaggerのサイトにはブラウザ上で試せるSwagger Editorというものが用意されており、左側にAPI記述を書くと、右側に生成されるドキュメントのプレビューを見ることができます（下図）。これを少し試すとSwaggerの雰囲気がすぐつかめると思います。（APIの記述はJSONではなくYAMLなので気をつけてください）

  • オープンでベンダーや実装言語などに依存しない。仕様はGitHubで公開されておりApache 2.0ライセンスで利用できます。
  • エコシステムが充実。コミュニティによりさまざまな言語に対応した多彩なツールやライブラリが作られています。
  • 賛同・ユーザ企業の多さ。Swagger 2.0仕様はオンラインサービスのPayPalã‚„Getty Images、API関連企業のApigeeã‚„3scaleを始め、500近くの大小企業の貢献で作られました。Microsoftã‚„米政府も使っています。

2. バージョンについて

2014/09/08に最新のSwagger 2.0がリリースされました。2.0は、これまでの1.x(最新は1.2)系とは互換性がないので注意が必要です（マイグレーションガイドはこちら）。2.0がまだ出たばかりなので、web上で見つかる日本語のSwagger記事はほとんど1.x系のものです。注意してください。

3. Swagger対応の便利ツール

Postman
みんな大好きAPIテストクライアントの定番、PostmanにもSwaggerインポート機能があります（Swagger 1.2対応）。
Mockable
REST/SOAPなモックサーバを簡単に立ち上げられる期待のサービス、MockableでもSwaggerインポートをサポート予定です（現時点では未実装）。
Apigee 127
APIモデル定義をベースに、Node.jsでの実装スケルトンを生成したり、キャッシュやレートリミット、OAuthなどのAPI管理機能を簡単に実現できるオープンソースプロジェクト、Apigee 127でもSwagger 2.0が基盤技術として採用されています。

まとめ

Swaggerは現在メジャーバージョンの移行期にあるため、ツールやサポートに若干の混乱はありますが、2.0への移行完了後がとても楽しみな技術です。Web API好きならば今のうちに試してみる価値はありますよ！

Raspberry PiでGroovy! #gadvent2012

G* Advent Calendar 2012もいよいよ最終日となりました。昨日は @shuji_w6e さんのJavaのテストコードからはじめるGroovyでした。

さて、７月に注文していた話題の低価格シングルボードコンピュータ、Raspberry Piがつい先日、ようやく我が家にも届きました。タイミングよく、Raspberry Pi上で動作するJDK 8の開発者プレビュー版（JavaFXも含む！）がリリースされたので、こいつをのっけて、さらにその上にGroovyをふりかけて遊んでみました、という話です。

1. Linux/JDKを載せる

詳しくはこちらをご覧ください（訳しておきました）：
Raspberry Pi で JavaFX - かんたん3ステップ

ここでは実際にやってみてわかった注意事項などをいくつかあげておきます：

  • 電源コネクタはMicroUSB。デジカメでよく使われているMini-USBとは別物なので注意
  • 電源は5V、Model-Bでは700mA以上必要。スマホ充電用の電源ケーブルを購入したが、USB 3.0であれば900mA以上の給電能力があるのでMacBook Proなどからでも大丈夫との噂も。
  • SDカードについては、4GB/Class 4より大容量／高速のものは避けろ、とあったり、逆にJDKのドキュメントのようにClass 10で大容量推奨、などとさまざまな情報があり混乱している。私は余っていた4GB/Class 6のものを使ってみたが特に問題なし。
  • カードにイメージを書き込む際、Macで RPi-sd Card Builder を使う場合はイメージファイルのパスに空白が入っていないことを確認する。私は"Raspberry Pi"というフォルダに入れていてハマった。
  • ロケールはja_JP等に設定しない方がよい。コンソールや設定メニューが日本語になり文字化けしてしまうため。
  • sshは絶対にenableにしておくこと！（理由は後述）

2. JavaFXで遊ぶ

JavaFXのサンプルアプリがJDKの開発者プレビューと同じページからダウンロードできます：
http://jdk8.java.net/fxarmpreview/

以下のアプリが含まれています：

  • StopWatch
  • BouncingBall
  • Calculator
  • BrickBreaker
  • FXML-LoginDemo
  • SwingInterop
  • Ensemble

まともに動くのは上の５つだけで、それらもお世辞にも安定しているとは言えませんが。。

アプリを動かすには次のようにします：

java -Djavafx.platform=eglfb -cp /usr/local/java/jre/lib/jfxrt.jar:BrickBreaker.jar brickbreaker.Main

DオプションでEGLFBモードを指定します。これはX Windowなどを介さず直接OpenGL上で動作するモードで、現在唯一の選択肢です。JavaFXアプリが画面を占有して動作するので、コンソールから直接起動してかまいません。ただし、上記のアプリには終了ボタンなどがなく、このモードでは終了する方法がなくなるため、必ず別途sshでリモートログインしておき、psとkillで終了できるようにしておきましょう。

jfxrt.jarは（まだ）デフォルトではクラスパスに入っていないので、明示的に指定する必要があります。あとは、アプリ固有のjarファイルと、メインクラスを指定します。

下記はおなじみBrickBreakerとCalculatorが動作している画面です：

3. Groovyで遊ぶ！

Java SEが動くということはすなわちGroovyも動く、ということです！普通に最新版のGroovy 2.0.6をインストールして試してみました：

よしっ！groovyshとgroovyConsoleが動いているのがおわかりいただけるでしょうか？

今回のG* Advent Calendarの12/2分で@tyama さんが作ったリズムボックスも動かしてみました：

（ちなみにRasberry Piにはスピーカはありません。HDMI経由でテレビから音がでています）

ここまで順調に動作しているように見えると思いますが、実は大問題が。遅い、とにかく遅すぎる。groovyshなんて立ち上がるまで30秒くらいかかります。grovyConsoleではキータイプについてこれません。実用はおろか、デモにも厳しいレベルです。Javaのパフォーマンスは悪くないので、何か特殊な原因があるような気がしますが、今回は調査が間に合いませんでした。ごめんなさい。

さらにこの先、GroovyFXまで進む予定だったのですが、JavaFXの実装が不完全（WebViewやMediaViewなどが未実装）な関係で、初期化時にエラーになってGroovyFXが起動できませんでした。残念無念！このへんも近い将来挽回できると思います。

まとめ。そしてOne More Thing...

以上、噂のデバイス、Rasberry PiでのGroovy実験レポート第一弾でした。注文してもなかなか手に入らないデバイスですが、最近は増産体制も整ったとの噂ですし、標準メモリも256MB→512MBにアップしています。三千円台で買えるわりにはかなり遊べるデバイスですので、まだの方はぜひ注文してみてはいかがでしょうか。

さて、これで2012年のG* Advent Calendarも完了です。参加していただいたみなさん、お疲れさまでした＆ありがとうございました。最後に「プログラミングGroovy」の執筆チームからのクリスマスプレゼントとして、

プログラミングGROOVY別冊：第８章 Groovy 2.0の新機能
をお届けします！ニューキャストさんのmybetabook（Grails製！）を使った、ペンギン本のバーチャル別冊です（無償）。本書を買われた方もまだの方にも楽しんでいただければ幸いです。

ではみなさん、Groovyな良いお年をお迎えください！

複雑なアニメーション（SVG版のGroovyFX版）

id:the48さんが前のエントリのサンプルアニメーションのSVG版を書かれていました：
複雑なアニメーション（SVG版） - 48's diary

JavaFXに含まれている内蔵ブラウザはSVGをサポートしているので、実はこのSVG版もJavaFX/GroovyFXで簡単に動かすことができます。

以下はGroovyFXで書いた例です。SVG部分はid:the48さんのをコピペしました。

JavaFXのWebコンポーネントについては下記もどうぞ：

[JavaOne Tokyo 2012] JavaFX and Web Integration