APIはシステム用の機能になります。分かりやすいビジュアル化された画面がある訳ではありませんので、使い方のドキュメントが必須です。 今回はAPIドキュメントを生成するためのライブラリを紹介します。 Swagger | The World's Most Popular Framework for APIs. SwaggerはRESTfulなAPIドキュメント生成に対応したツールとなっています。ドキュメントはYAMLを使って記述します。また、Web上でテスト実行できる仕組みが便利です。 RAML - RESTful API modeling language RAMLとはRESTful API Modeling Languageの略で、YAMLフォーマットを使ってRESTfulなAPIドキュメントを作成します。専用のエディタもあり、プレビューで確認しながらドキュメントが書けます。 apiDoc - Inline Documentation for RESTful web APIs apiDocは各プログラミング言語にコメントを使ってインラインで記述するAPIドキュメントになります。JavaDocやPHPDocなどに近いものです。ドキュメントとソースコードが近くにあるので内容が乖離しづらいのが利点でしょう。 API Blueprint - API Documentation with powerful tooling API BlueprintはMarkdown記法に沿って書くAPIドキュメントです。単純にドキュメントだけでなく、API BlueprintをベースにしたAPIモックサーバ、テストツールなどが存在します。 mashery/iodocs JSONフォーマットで定義するAPIドキュメントになります。ドキュメント上から実際にAPIのコールができるのが特徴になります。 rjha/restdoc PHP製のスクリプトでYAMLフォーマットの定義からドキュメントを生成します。スクリプト言語なのでYAMLを更新するだけでいつでも最新のドキュメントが読めるのは良さそうです。 MireDot | REST API Documentation Generator for Java Javaで作られたシステム用のAPIドキュメントジェネレータです。JavaDocのように簡単に、とあるのでJavaDocを書かれた経験がある方であればすぐに使いこなせるでしょう。 ehearty/Swadl RESTful APIにおけるWSDLとも言えるWADLをベースにドキュメントを生成するソフトウェアです。 Apiary - Home APIの仕様を定義するとドキュメントの生成はもちろん、APIモックの生成、コードサンプル、テスト自動化など複合的にサービスを提供しています。 tombenke/rest-tool nodeで作られたライブラリで、JSONフォーマットで定義した内容を読み取ってドキュメントを生成します。 malachheb/calamum JSON/YAMLで書かれたファイルからドキュメントを生成します。 APIドキュメントを適切に整備していくためにはツールの使いやすさはもちろんのこと、ベースになる記法やそのルールの分かりやすさも重要になってくるでしょう。 ぜひこれらのツールを参考に、他の開発者にとって分かりやすいドキュメントを書いてください。

9/3夜に、Enterprise APIs Hack-Nightという勉強会を開催します！ 日時：2015/9/3(木) 19:00-22:00(18:30から受付開始) 場所：TECH LAB PAAK(東京都渋谷区神南1-20-9-6F) ＊お申し込みはこちらから↓ http://eahn.connpass.com/event/18013/ Enterprise APIs Hack-Nightとは ビジネスレベルでのAPIの活用事例や関連技術を共有するオープンな勉強会です。 第１部では30分程度の講演を3コマ用意しています。Apigee Japanの関谷さん・清水さん、MOONGIFTの中津川さんにご登壇いただく予定です。 また、今回は初開催ということで、NTTコミュニケーションズが提供するAPIのご紹介もさせて頂きます！ 第2部では懇親会＋LT大会を予定しています。 LTは自由参加です。まだ枠に空きがありますので、我こそはという方は是非ご登壇ください！ ＊LT希望の方は申し込みサイトから登録してください APIがビジネスに与えるインパクト この勉強会のサブタイトルでもありますが、新サービス創出、企業間連携、プロセス自動化、企業にある資産（情報）の有効活用などの手段としてAPIの重要性は高まってきています。 では、ビジネスでAPIを活用していくために留意すべき点は何か、どのようなユースケースがあるのか、お客様はどのようなことを求めているのか、など情報交換ができればと思っています。 APIに興味がある方ならどなたでも 主にデベロッパ向けのプログラムとなっていますが、ユースケースやデモのご紹介もありますので、APIに興味がある方であればどなたでもご参加ください。 今回は残念ながら参加が難しい・・・という方も、今後定期的に開催していきたいと思っていますので（好評であれば東京以外でも）、 引き続きウォッチしていただければと思います。

ここ数年、エンタープライズ分野において注目を集めているのがAPI管理サービスです。Webサービスからだけでなく、スマートフォンアプリや外部システムからもアクセスされるだけにパフォーマンスを可視化したり、自社のデータを加工して素早くWeb API化したいといった要望が出ています。 API管理サービスを使うことで自社のデータを素早く、かつ安全にAPI化できます。今回はそうしたサービスをまとめて紹介します。 3scale API Management Platform Webサーバにプラグインとして導入し、トラフィックのコントロールであったり、トークンごとの課金管理も行えます。管理画面ではAPIアクセスを解析したり、ポリシーの設定、APIドキュメントの展開も可能です。 Mashery API Management 社内のデータをセキュアな状態に保ちつつ、Masheryを使ってAPIを公開したり、トラフィックを管理することができます。クラウド版とオンプレミス版があり（もしくはその両方）、ニーズに応じて組み合わせられます。なお、MasheryはIntelに買収されています。 Apigee APIのトラフィックやステータスを監視してくれたり、APIのデザインも自由に行えます。課金の管理やスケールなども自動で行われますので、データを持っている企業はApigeeと組み合わせることで新しいビジネスの可能性が出てくるでしょう。 APIBond 既に公開されているAPIとアプリケーションの間に立ち、コンテンツの変換であったり、解析、検証、セキュリティの維持を行ってくれるサービスになります。APIの返却名を変えたり、バリデーションを行うことで、より安全に使えるようになります。 Restlet ブラウザ上でAPIの設計を行い、そのまま公開できるサービスになっています。またJava向けにフレームワークを公開しており、AndroidやGoogle App Engineなどで同社の作ったAPIが素早く使えるようになっています。 Microsoft Azure API Management Microsoft Azureを使ってAPIの設計と公開ができます。クォート制限を行ったり、モニタリング、複数のバックエンドを単一のエンドポイントに集約、ドキュメント機能などが提供されています。 IBM API Management Service APIをコーディングレスで設計、公開できます。既存の資産を活かしてWeb API化でき、アクセス制御や監視、解析機能を提供しています。 Akana 既存のAPIに管理機能を追加します。ドキュメント管理、解析、マネタイズなどの機能が追加されます。 Mashape APIのマーケットプレイスを提供しているサービスです。APIの返却するフォーマットを変換したり、アクセスコントロール、モニタリング、アラートそして課金管理も行います。 Amazon API Gateway Amazon Web Servicesの一つとして最近リリースされたのがAmazon API Gatewayです。Amazon API Gatewayをフロントエンドとして、EC2やAWS Lambda、任意のWebアプリケーションにアクセスするAPIを作成できます。Amazon API Gatewayは主にトラフィック管理、認証、アクセス管理、モニタリング、バージョン管理などを提供します。 それぞれサービスによって提供される機能は異なりますが、既にあるWeb APIに解析、セキュリティ機能を追加するものであったり、全くのゼロからWeb APIを設計できるものもあります。既存の資産を活かし、ビジネスをさらに飛躍すべくWeb APIを活用してください。

APIとAPIを組み合わせてマッシュアップサービスを作ろうと思った場合、まず自分が欲しいデータを提供しているAPIを探す必要があります。今回はそんなAPIのディレクトリを提供しているサービスをまとめて紹介します。 PublicAPIs 執筆時点で5,330のAPIから検索ができるAPIインデックスサービスになっています。名前やAPI名などを入れることで、新しいAPIの登録申請もできるようになっています。 PublicAPIs | Directory of public APIs for web and mobile API For That 検索、ソーシャル、ファイナンスなど約20のカテゴリに分かれて登録されています。約300種類くらいのAPIが登録されています。 API For That | An API Directory Zapier IFTTTのビジネス版と言った雰囲気のサービスになっています。2つのサービスを連携させてアクションを起こします。Exploreメニューから多くのAPIにアクセス可能です（Zapierが使えるものに限られます）。 The best apps. Better together. - Zapier ProgrammableWeb APIのディレクトリ、ニュースを配信しているサイトです。13,000種類を超えるAPIが揃っています。日本のAPIは多くありませんが、世界中のAPIを探すならまずここを当たるのが良さそうです。 ProgrammableWeb - APIs, Mashups and the Web as Platform Mashup Awards 日本のAPIを探すのであればMashup AwardsのAPIリストページを見ると一番揃っているのではないかと思います。海外のものもありますが、250種類近くのAPIが一覧化されています。 APIリスト | MA【エム・エー】 by Mashup Awards 天気やホテルなど位置情報に基づくサービスはその国のサービスが提供しているAPIを使う方が精度が高いように見えます。とはいえ、二つのAPIを組み合わせることで思いもしなかった効果が見いだせる可能性だってあるでしょう。 自分が作りたいものを決めてからAPIを探すのも良いですが、逆にリストを眺めてインスピレーションを得るというのはいかがでしょうか。

1. マルチデバイス、マルチプラットフォーム 今やAPIはWebアプリケーションに限らず、スマートフォンやタブレットアプリ開発においても欠かせぬ存在になっています。そのため元々WebアプリケーションをAPIを使って開発しておくことで後々のスマートフォンアプリへの対応も同じAPIを使って開発ができます。同様にWindows/Mac OSXなどの異なるプラットフォームへの対応も行えます。 もちろんプラットフォームによって対応できる機能の違いはあります。特に認証や課金周りは仕組みが違うことがあります。しかし予め分かっている場合は各プラットフォームに縛られる技術ではなく、汎用的なAPI設計にしておくのが重要でしょう。 2. フロント/バックエンドの疎結合化 従来のWebシステム開発の場合、サーバサイドでHTMLをレンダリングしていましたが、それによってフロントエンド（見た目）の回収はサーバサイドのシステムへの修正が必要でした。フロントエンドとバックエンドがAPIによって疎結合化することでそうした面倒さはなくなり、HTMLではなくJSONやXMLのように授受されるデータフォーマットを基にした仕様決めが可能になります。 なお、この手の場合常に話題になるのがSEO対策ですが、主に2つの解決方法があります。 クローラー向けにサーバサイドレンダリングにも対応する moviepilot/seoserver のようなソフトウェアを用いる 1についてはサーバサイドとクライアントサイドでテンプレートが重複してしまうのが問題です。そのため、例えばReactを使うことでサーバサイドとフロントエンドで共通のテンプレートが利用できるようになります。2の場合は特定の技術に依らずに使えるのがメリットですが、表示処理に多少時間がかかってしまうのが難点です（最近のGoogleクローラーは表示までの速度をランキング上のパラメータにしているという話です）。 3. サーバサイドの改修コストを抑える APIはURL単位のマイクロサービスに分割することが可能です。そのため、将来的にフレームワークのバージョンを上げたり、プログラミング言語自体を変えたいと思った場合、一部の機能だけ問い合わせ先のアプリケーションサーバを切り替えると言ったことが容易にできます。これはAPIの先はブラックボックスになっているメリットと言えるでしょう・ 最近の技術革新は速く、最新のフレームワークに乗り換えることで開発効率が大幅に向上したり、実行速度も格段にあがります。そうした中、既存のシステムが足かせになってしまうのは大きな問題で、かといったすべてを乗り換えるコストはとても大きいものになります。APIを使うことで一部から順番に移行していくことが可能になります。 4. 処理の単純化 RESTfulな設計を行っている場合、一つ一つのアクセスはそれぞれ一つのモデルに対する操作になります。そのためロジックが複雑化せず、一つ一つのリクエスト処理は高速に実行できます。これはクライアント、サーバ双方にとってのメリットです。ただし複数のデータを組み合わせて処理する場合、リクエスト処理が増えてしまうのが問題になります。ネットワークのレイテンシーは無視できないほど大きいため、ロジックをシンプルにするのとネットワークアクセス頻度は常にトレードオフになりえるでしょう。 解決手段の一つとして、一つのリクエストの中で複数のURIを含めるバッチ処理をサポートするという方法があります。実際にはWebサーバがプロキシになってバッチ処理をアプリケーションサーバに投げて、その結果を一つにしてクライアントに返却するというものになります。これによりサーバ側とクライアント側両方のニーズが叶うでしょう。 5. 将来的な追加開発コストの低減 システムの開発コストを引き上げるものは複雑性です。特に追加開発時は複雑なものに対していかに後方互換性を失わずに開発するかに頭を悩ませることになります。そして度重なる追加開発の結果としてバグが入り込むことになります。 APIの構造をシンプルに保てれば、それだけ追加開発のコストを下げることにつながるでしょう。シンプルであれば保守性もよく、バグが混入する余地も小さくなります。APIファーストな設計はシステムライフサイクルをスムーズにします。 6. 外部企業とのシステム連携が容易に 他の企業とのシステム連携を行う場合、必ずAPIが必要になります。連携が決まってから開発していると時間がかかるのはもちろん、その個別企業との取引に最適化されてしまうことがあります。その結果、別な企業との連携が必要になるとまた一から開発し直しになります。 予めAPIがあることで連携が容易になるのはもちろんのこと、万一追加機能が必要であっても元々の設計標準に従って開発することができます。それは個別の企業に特化せず、汎用的かつ安全性の高いAPIになることでしょう。 7. 高スケーラビリティ 一つのサーバでHTTP/アプリケーション/データベースを提供し、かつサーバとクライアントサイドが密接に関わっている場合、どこがボトルネックになっているのか調べるのは困難です。またボトルネックが分かったとしてもスケールさせる際にはシステム全体の設計を考え直す必要があるかも知れません。 APIファーストの場合、元々サーバサイドとクライアントサイドが分離しています。その結果、どこがボトルネックになっているかが分かりやすく、かつ一般的にAPIは単一のURIで提供されますのでスケールしやすくなっています。 いかがでしょうか。今後、スマートフォンやタブレットはエンタープライズにおいても一般化していきます。そうした中でそれぞれ個別に開発していては時間もコストもかかりすぎてしまいます。APIを最初に設計、開発しておくことで将来的な広がりが容易に実現できるようになるでしょう。 また、サーバ/クライアントサイドを疎結合にすることで保守性を高めたり最新技術への追従も容易になります。今後システム開発を行っていく際にAPIファーストに進めてみてはいかがでしょうか。

アプリ、Webサービスと数多くのインターネットを使ったサービスが登場するのに比例してWeb APIも次々と作られています。Web APIのマーケットが拡がっていくことで認知が高まり、さらにWeb APIが開発されていくという好循環が生まれています。 その一方で乱立することによって、Web APIの品質が問題になってきます。Web APIではWebブラウザを使ったアクセスとは異なり、基本的にプログラムからのアクセスを考えなければなりません。そのため不用意なセキュリティホールがあったりすると、あっという間に大きな問題（データの消失であったり、乗っ取りであったり）が発生する可能性を秘めています。 そこで私たちはWeb APIの設計に際して標準規則を策定しています。その規則に沿ってWeb APIの開発を進めることで、可用性はもちろん堅牢性や安全性を意識した情報の提供ができるようになります。これまでのインタフェース、データフォーマット、バージョン管理、同期・非同期に続き、今回は セキュリティ について規則の一部を紹介します。 認証処理の種類 Web APIの種類によって以下の選択肢が考えられます。 OAuth 2.0 HMAC APIトークン SSLクライアント証明書 認証なしでのWeb API利用やBasic認証での利用は原則としてお勧めしません。 通信はHTTPS 外部に公開されるものについては正規のSSL/TLS証明書を用いますが、社内システム間や社内の接続元が保証される場合においては独自の証明書でも可能としています。しかしデータ漏洩防止の観点から、Web APIはHTTPS接続のみと言うのが安心でしょう。 定期的な監査、クリーニングの実施 Web APIの利用時はアカウント、またはアプリケーションごとにトークンを発行します。しかしこの手の運用として不要となった時に適切に削除されていないことが多々あります。トークンの利用状況について一覧できる画面または機能を予め用意した上で定期的に整理するのが重要です。 また、ログを適切に残すことにより不正アクセスに対して対応することができます。ここでいう不正アクセスとは例えば、 パラメータ改ざん DoSアタック などが考えられます。パラメータ改ざんについてはシステム側でのバリデーション、SQLインジェクションチェックなどを適切に行うことで回避が可能です。DoSや大量アクセスについてはWeb APIという仕様上致し方ない部分もありますが、閾値を超えた段階でそのためのエラーコードを返したり、予めレスポンスをキャッシュする機構を組み入れておく必要があるでしょう。 レスポンスは200ms以下で Web APIのレスポンスは基本、200ms以下であるべきと考えています。これは一定の基準であって、システムによって異なる場合があります。ただし基準を設けることで性能劣化に気づくことができたり、重たいWeb APIについては機能を分割すると言った工夫もできるようになるでしょう。 Web APIはシステムから自動的に操作されることが多いため、問題があると一気にすべてのデータが漏洩したり、削除されたりする可能性を秘めています。そのためセキュリティ要件については特に慎重に考える必要があるでしょう。 ぜひ皆さんのWeb API設計において参考にしてください。

アプリ、Webサービスと数多くのインターネットを使ったサービスが登場するのに比例してWeb APIも次々と作られています。Web APIのマーケットが拡がっていくことで認知が高まり、さらにWeb APIが開発されていくという好循環が生まれています。 その一方で乱立することによって、Web APIの品質が問題になってきます。Web APIではWebブラウザを使ったアクセスとは異なり、基本的にプログラムからのアクセスを考えなければなりません。そのため不用意なセキュリティホールがあったりすると、あっという間に大きな問題（データの消失であったり、乗っ取りであったり）が発生する可能性を秘めています。 そこで私たちはWeb APIの設計に際して標準規則を策定しています。その規則に沿ってWeb APIの開発を進めることで、可用性はもちろん堅牢性や安全性を意識した情報の提供ができるようになります。これまでのインタフェース、データフォーマットに続き、今回は バージョン管理、同期・非同期 について規則の一部を紹介します。 バージョン管理について Web APIのバージョン管理は常に話題にあがってきます。対応方法としては以下のパターンが考えられます。 URIのパスにバージョン番号を含める URIのパラメータにバージョン番号を含める 新しいWeb APIを作る 3.の新しいWeb APIを作る方法は機能の乱雑化を生みますし、メンテナンスコストを著しく悪化させるためお勧めできません。2.のパラメータに含める（/api?version=2など）はキャッシュの兼ね合いやロジックの複雑化につながる可能性があります。 そこで私たちはURIのパスにバージョン番号を含める方法を基準としています。つまり次のような形です。 https://example.com/v1/api v1がバージョン番号にあたります。こうすることでWeb APIの実装が大幅に変更された場合においても下位互換性を維持することができます。 同期・非同期の分け方について Web APIの場合、クライアントからネットワークを使ってアクセスしてきますので、あまり長時間のネットワーク接続が求められるものはタイムアウトしてしまう可能性があります。そのため最長でも30秒程度までを同期処理、それ以外は非同期処理として実装するのが良いでしょう。 エンタープライズレベルでのWeb API実装においてはトランザクション処理が求められることが多々あります。しかしHTTPを使ったネットワークとトランザクションは相性が良くありませんので、トランザクションを用いた処理の場合は非同期処理を用いるのが良いでしょう。 Web APIは一度作ったら終わりではなく、随時更新、変更されていくものです。この点においては通常のWebサービス、Webシステムと同様と考えられます。ただしWebサービスなどはUIを変えても利用者が使い方を習得してくれる一方、Web APIはリリース後は自動運転されることが多いので旧来の接続クライアントに常に気を配っておく必要がある点を注意してください。 ぜひ皆さんのWeb API設計において参考にしてください。

アプリ、Webサービスと数多くのインターネットを使ったサービスが登場するのに比例してWeb APIも次々と作られています。Web APIのマーケットが拡がっていくことで認知が高まり、さらにWeb APIが開発されていくという好循環が生まれています。 その一方で乱立することによって、Web APIの品質が問題になってきます。Web APIではWebブラウザを使ったアクセスとは異なり、基本的にプログラムからのアクセスを考えなければなりません。そのため不用意なセキュリティホールがあったりすると、あっという間に大きな問題（データの消失であったり、乗っ取りであったり）が発生する可能性を秘めています。 そこで私たちはWeb APIの設計に際して標準規則を策定しています。その規則に沿ってWeb APIの開発を進めることで、可用性はもちろん堅牢性や安全性を意識した情報の提供ができるようになります。前回のインタフェースに続き、今回は データフォーマット について規則の一部を紹介します。 データフォーマットはXMLまたはJSON 現在、Web APIで送受信されるフォーマットはXMLまたはJSONがデファクトスタンダードになっています。特に一般開発者向けに公開されるものはWebブラウザからも扱いやすいJSONが増えています。Webサービスをはじめ、エンタープライズ間でやり取りされるデータについてはXMLを使うことも多いです。 データのやり取りに際して旧来の手法であるCSVについては現在は非推奨とすべきです。項目の順番や長さによるデータ定義や改行やエスケープすべき文字が入った時の処理など、扱いの柔軟性が問題になります。 Web APIにおけるフォーマットの指定 Web APIが返す出力についてはリクエスト時にフォーマットが指定できるようになっているべきです。例えばURIで指定する場合は次のようになるでしょう。 http://example.com/〜.json # JSONリクエストの場合 または format パラメータに jsonまたはxmlなどと文字で指定する場合もあります。formatパラメータの場合、jsonp（JSON with padding）を指定することも考えられます。URL指定の場合はcallbackパラメータのあるなしでJSON/JSONPと出力を変えることが多いように見えます。 http://example.com/〜?format=json いずれの場合においても利用者が使いたいと思うフォーマットを動的に指定できるのが望ましいと考えています。 スキーマの提供 XML、JSONのいずれにおいても実装とAPI仕様の乖離を避けるためにスキーマを提供すべきです。XML Schemaは昔からよく知られていますし、JSONにおいても JSON Schema が定義されています。 パラメータ命名規則について パラメータ名は分かりやすいものをつけるのは当然ですが、大文字小文字についても注意が必要です。私たちはLCC（Lower Camel Case）を推奨しています。例えばユーザ名であればuserNameといった形で先頭を小文字に、その後の単語は頭を大文字にしています。その他の手法としては_（アンダースコア）を使う場合もあるかと思います。 文字エンコード 文字エンコードはUTF-8であるべきです。日本語をはじめ、複数バイト文字圏ではエンコーディングが最大の問題、かつ不具合の原因になりますので、UTF-8を使っておくのが安全であり、基本になるでしょう。 Web APIは人ではなくシステムを対象にして開発されています。そのため内部の実装がブラックボックスになり、Web APIおよびそのドキュメントがそのまま仕様として外部に公開されることになります。適切なWeb API設計を行うことがシステムの可用性、柔軟性、堅牢性につながることでしょう。 ぜひ皆さんのWeb API設計において参考にしてください。

アプリ、Webサービスと数多くのインターネットを使ったサービスが登場するのに比例してWeb APIも次々と作られています。Web APIのマーケットが拡がっていくことで認知が高まり、さらにWeb APIが開発されていくという好循環が生まれています。 その一方で乱立することによって、Web APIの品質が問題になってきます。Web APIではWebブラウザを使ったアクセスとは異なり、基本的にプログラムからのアクセスを考えなければなりません。そのため不用意なセキュリティホールがあったりすると、あっという間に大きな問題（データの消失であったり、乗っ取りであったり）が発生する可能性を秘めています。 そこで私たちはWeb APIの設計に際して標準規則を策定しています。その規則に沿ってWeb APIの開発を進めることで、可用性はもちろん堅牢性や安全性を意識した情報の提供ができるようになります。今回はその項目の一つである インタフェース について一部を紹介します。 REST APIであること 昨今のWeb APIの流れはREST APIにあります。つまりURLでデータ（リソース）を特定し、HTTPメソッド（GET/POST/PUT/DELETE）によってそのデータに対して行う操作を特定します。技術的に言うと、 HTTPメソッド 操作 GET READ POST CREATE PUT UPDATE DELETE DELETE に対応させるということです。詳しくは REST - Wikipedia をご覧ください。 プロトコル これから作られるWeb APIについてはHTTP 1.1になっているべきでしょう。HTTP 1.1についてはKeep-AliveとHOSTヘッダの特徴が挙げられますが、一般的なHTTPサーバであるApacheやnginxなどを利用している限りは特に意識することはないかと思います。Web APIを提供する上ではあえて独自のプロトコルを定義するようなことは避け、標準技術に沿って進めるのが良いでしょう。 Content-Type Web APIはデータを返却する際に適切なContent-Typeを設定しておく必要があります。今のトレンドとしては、XMLとJSONがあるかと思います。 XML XMLで使われるContent-Typeは以下の5つがあります。これは RFC 3023 で定義されています。 text/xml application/xml text/xml-external-parsed-entity application/xml-external-parsed-entity application/xml-dtd Web APIとして用いる上では application/xml がお勧めです。 JSON JSONで使われるContent-Typeは application/json のみ定義されています。これは RFC 4627 に記載されています。なのでJSONデータを返却する際には application/json を Content-Type として指定しましょう。 適切なWeb APIを設計すると、リリース後の更新において設計が破綻することがなかったり、拡張性も担保されるようになります。もちろん、設計が統一されることで不用意なセキュリティホールが出るのを防ぐこともできるでしょう。 エンタープライズにおけるWeb API開発および利用や評価において参考にしてください。

Web APIは自動化を担う仕組みになりますので常に一定のパフォーマンスが求められます。単純にアクセスしてレスポンスを返せばいいだけでなく、パラメータに対してロジックを実行した上で素早くレスポンスを返す必要があります。 今回はそうしたWeb APIのパフォーマンスをテストするロードテストに使える外部サービスを紹介します。 On Demand Load Testing for Developers & Testers | Load Impact 専用のツールを使って操作を記録し、その操作スクリプトに従ってロードテストを行います。スクリプトを修正し、異なるアクセス方法に変更することもできます。さらに異なるロケーションからのテスト（例えばイタリアなど）が行えたり、モバイル回線を使ったテストにも対応しています。 Application Load Testing Tools for API Endpoints with loader.io 無料で使えるのが大きなポイントのロードテストサービスです。APIも用意されていますので、Web API開発と組み合わせた運用も考えられるでしょう。 Performance and Load Testing from the Cloud - Blitz by Spirent 同時に20万の仮想ユーザおよび8つの異なるロケーションからのアクセスをサポートしています。Google ChromeとFirefox向けに機能拡張が提供されており、それを使うことでテストが容易に作れるようになります。自動化のためにはRuby向けのライブラリやAtlassian製のCIサーバと連携ができるようです。 Test Automation for DevOps パフォーマンステスト、CI連携のテスト、そしてモバイルパフォーマンステストが大きな特徴となっています。Apache JMeterと100%の互換性があります。テストについてはSeleniumを使っています。 API Performance Monitoring · Runscope テストは世界中の各地域から実行でき、Slackをはじめとして各チャットサービスに結果を投稿できるようになっています。監視サービスを含んでおり、問題が発生した時にすぐに気づける仕組みも提供されています。 Cloud Testing Platform | Cloud Load Testing for APIs and Websites, API & Website Monitoring and Website Speed Testing Tool for APIs, Websites and Mobile Applications Web APIのロードテストはもちろん、通常のWebサイトのモニタリングやスピードテストも行えるようになっています。 Apica | Advanced Load Testing Solutions. Flexible Load Testing Service Plans エンタープライズ向けにサービス提供されており、ハイボリューム（200万仮想ユーザ以上）でのロードテストが可能です。APIも提供されていますのでCIとの連携も行えます。 LoadUI - The Home of Load Testing | API Load Testing Tool LoadUIはSaaSではなくダウンロード型のソフトウェアになります。サーバの監視機能もあり、SaaSでは導入がしづらい企業においては良い選択肢になるのではないでしょうか。 ロードテストは負荷テストに比べてより実践的なデータを送受信するテストと言えるでしょう。そのためテスト設計が大変ではありますが、一度組んでしまえば後は自動化した上で開発する度にテストを自動実行できるようになります。 その上でデータが蓄積されて徐々に性能が劣化していくのをいち早くつかんだり、特に重たい処理を知ることで改善につなげることもできるでしょう。ぜひ使ってみてください。

Web APIというとWebサービス企業が外部の開発者に対してリリースし、マッシュアップを作ってもらうという印象があるかと思います。しかし、ここ数年はビジネスレベルにおいて企業間サービス連携としてWeb APIが利用されるようになってきています。 そこでエンタープライズレベルにおいてWeb APIをどのように使っていくべきか、または懸念点などを紹介したいと思います。 自動化 まず企業システムにおいて大事なのが自動化です。省力化し、対人コストを減らすことができます。特に電話やメールなどで問い合わせをし、それに対してオペレータが自社システムを検索した上でその返事をする程度であれば、そもそもWeb APIとして公開してしまうことができるでしょう。 その際に問題になるのはセキュリティではないかと思います。Web APIは一般的に各機能が独立して存在しており、それぞれの機能ごとに認証を行わなければなりません。そうなるとID、パスワードを記録しておく必要があるため、セキュリティ上のリスクになります。 そこでWeb API上でのみ使えるトークンを発行してパスワード代わりにしたり、OAuth2のような技術を使うのが一般的となっています。 企業間連携 お互いのサービスを連携させることでシナジーが生まれる場合、Web APIを用いた連携が行われます。よくあるのは旅行会社と航空会社のシステムであったり、最近では飲食店の予約システムとオンライン台帳システムが連携していたりします。お互いが足りていない機能を補完し合うことでサービスの利便性を高めるのに成功しています。 この場合、認証を介さない連携が行われることも多く、そのために接続できるIPアドレスを制限するのが一般的と思われます。また、完全に自動化した上で運用されるため、十分な相互接続テストが必要になります。 この利点としてはそれぞれの会社がWeb APIを作ってしまえば、同じ手法で他の企業とも連携できるようになるということでしょう。そのため、なるべく個別の企業向けに特化するのではなく、汎用的なWeb APIを作る必要があります。 従来は全銀協標準プロトコルやCAFISのような専用プロトコル、システムを定義していましたが、最近ではWeb APIを使ってインターネットを介してデータの送受信を行うのが一般的です。この場合、特にデファクトになるものがないケースはそれぞれドキュメントを用意した上で開発を行います。 クラウドサーバ ここ数年で注目の集まっているクラウドサーバにおいてもWeb APIが使われています。Web APIを通じてサーバをクラウド上に立ち上げる、または逆に消すといった操作が行われています。一時的にマシンパワーが必要になったタイミングで10数台（またはもっと）のサーバを立ち上げて処理を実行し、終わったら落とすと言った操作を行うことで膨大なマシンパワーを数百円程度で利用できるようになります。 また、サーバへのアクセスが増大した時に自動的に台数を増やして処理を並列化したり、必要がなくなったら落とすと言った具合にオートスケーリングさせるための仕組みや手法も広まっています。運用を自動化することはシステムの安定化において欠かせない要素になっています。そして、それを支える技術にWeb APIが使われています。 基幹システムとの接続 社内においてもWeb APIを使うことで業務を格段に早く、かつ確実なものにできます。外部のサービスにおいてはWeb APIを提供することが増えており、そうしたサービスからデータを引き出すことができれば基幹システムと接続して業務を自動化できます。 帳票や物流、倉庫業務など多くの場面において自動化が進められています。手作業でレポートやCSVをダウンロードしたり、転記したりするような手間はWeb APIを使うことで大幅に減らせるでしょう。 ジャストインタイム Web APIを使った場合の利点として、チェックを自動化できるということが挙げられます。問題が起きたり、状態が変わった時にチェックするといったこともWeb APIであれば簡単に自動化ができます。コンピュータは予め指定した処理を繰り返すのは得意であるため、そういった作業こそ自動化すべきでしょう。 そして閾値を越えたり、ステータスが変わったタイミングで担当者にメールなど、何らかのアラートを出すことができます。問題が起きた時に素早く対応できる体制はWeb APIを利用することで容易に実現できるでしょう。 データハブ Web APIを用意することで業務上、様々なところに散在するデータを一元管理することができます。例えばグループウェア標準のUIでは入力がしづらいケースもWeb APIがあれば専用のUIを作成し、運用が簡単になります。その結果、これまでは別途管理していたデータがグループウェアの中に一元管理されるようになります。 データが様々な場所にあるとそれだけ見る場所が増え、その結果として見逃すケースが増えてしまいます。Web APIを使うことでデータが集約されるとそれだけ運用コストが軽減されるでしょう。最近では Slack （Webチャットツール）が多くのサービスと連携し、メッセージハブとしての役割を担っています。 Web APIは単純に公開すれば良いというものではなく、その企業にとって戦略性を持ち合わせたものでなければなりません。特にエンタープライズレベルにおいては実際の業務上で利用されることを念頭においた設計、送受信されるフォーマットなどを考えなければならないでしょう。

Web APIのフォーマットとしてJSONの採用が増えています。JSONは軽量な記述言語で手軽に扱える反面、そのデータ内容に対する保証がしづらいのが問題視されています。そこで注目を集めているのがJSONの構造を定義するJSON Schemaです。JSONデータに対して型やメタ情報を付与することでフォーマットに対するルールを追加します。 JSON Schemaは現在仕様として策定が進められています。詳細は JSON Schema and Hyper-Schema にて確認することができます。 今回はJSON Schemaを導入することでどのような可能性が見えてくるのか考えてみたいと思います。 1. バリデーション まず最初に思いつくのはバリデーションです。これはクライアント、サーバ両方について行えます。データをポストする前に検証したり、受け取ったデータについてバリデーションを自動的に行えるようになります。 検証結果がエラーであれば、それをそのまま返せば良いでしょう。検証後の利用についてはデータ構造や型が保証されるので安心してコードを組めるようになります。 2. データを扱うライブラリの生成 こちらはWebサービスでよくあったスキーマ（WSDLなど）からコードを自動生成するのに似ています。Javaや.NETであればスケルトンコードを生成する形に、RubyやPHP、Pythonなどのスクリプト言語であればメソッドを自動生成する形になるでしょう。 JSONはパースした後、ハッシュや連想配列で扱うことが多いですが、予めコードを生成することでより扱いやすいデータとして使えるようになります。 3. ドキュメント生成 さらにJSON Schemaではデータ構造やURLに対する記述やパラメータの説明も行いますのでAPIドキュメントを生成するのにも使えます。実際のコードとは分離しますので整合性を保つ必要はありますが、後述するテストする仕組みと組み合わせることで最新の状態に保つことができるでしょう。 APIドキュメントを参照する開発者は多いので、このようなアウトプットがあることでJSON Schemaを適切にメンテナンスしていこうというモチベーションにもつながるはずです。 4. ダミーサーバ Web APIを扱うライブラリのテスト用サーバのベースとしてJSON Schemaが利用できます。サーバ内のロジック部分について保証できるわけではありませんが、ダミーサーバがあることでローカルでの開発やテスト環境下での実行が容易になります。 ただしダミーサーバでは入力値の必須や型などのチェックはできても、トークンの妥当性といったようなロジックのチェックはできません。あくまでも開発時の補助ツールとして使うのが良いでしょう。 5. テストの自動化 そしてWeb API自体のテストを行う際にもJSON Schemaが使えます。予め定義した値をポストして、予定されている結果が得られるかどうかを検証できます。Web APIの拡張を行っていて、例えば新しい必須項目を追加したためにこれまでWeb APIを使っていたシステムが突然動かなくなることがあります。そうした点においてもJSON Schemaをバージョン管理し、全てのバージョンで動き続けているかをチェックできるのは重要です。 Web APIを使ったソフトウェアは完成後、自動運転のフェーズになることが多々あります。そうした時でも結果を担保するためにJSON Schemaが利用できるでしょう。 6. 開発時のエラーチェック IDEなどであればJSON Schemaを取り込むことで予め警告を表示できるようになるでしょう。JSONの構造はテキストのままでは可読性が低く、読み違えることが多々あります。そうしたミスを防ぐのに使えるはずです。 JSON Schemaは幾つかのメリットがありますが、元々がWSDLなどの複雑さや面倒さから逃れるために生まれたこともあってなかなか普及していません。しかし今後エンタープライズレベルでWeb APIが使われていく中では重要な要素になってくるはずです。 単にやるべきだからやる、ではなくJSON Schemaを使って開発生産性を高めたり、ドキュメントを自動生成するなど負担を軽減することができれば、もっと使われていくのではないでしょうか。

Web APIという単語が出てきたのはおそらく2003年頃で、Web 2.0という単語が広まってきた頃でした。元々その前進としてWebサービスがありましたが、そちらは主にエンタープライズ向けでSOAP（元々はSimple Object Access Protocolの略）を使ってデータの送受信を行うものが多かったと記憶しています。 Webサービスは主に企業間でインターネットを介したデータの送受信を期待して作られていましたが、構築時のコストに比べてメリットが少なかったり、利用までの敷居が高いこともあってあまり広まりませんでした。GoogleやAmazonもSOAPベースのAPIを提供していましたが、今はもうありません。 そんな中台頭してきたのがWeb APIになります。APIとはアプリケーション・プログラミング・インタフェース（Application Programming Interface）の略で、Webサービスをプログラミングから操作するための方法といった意味になります。Web APIは前述の通り、Web 2.0という単語が出てきたのに合わせて注目が集まりました。記憶を辿ると、最初はDeliciousやFlickrといったサービスがデータの取得だけでなく、投稿（ブックマークや写真を新規作成する）機能をWeb APIとしてリリースしたのが最初ではないでしょうか。その後、多くのWebサービスがWeb APIをリリースしはじめ、現在では新しくサービスを作る場合にはWeb APIを予め用意しておくものといった雰囲気さえあります。 フォーマットはJSONが基本 Web APIが出始めた頃はXML形式でデータの送受信を行うものが多かった覚えがあります。要因の一つとしてはRSSフィードがあります。RSSフィードはブログの文化とともに成長し、今では殆どのブログがRSS（またはAtom）フィード出力をサポートしています。そのRSSフィードがXML形式であり、多くのライブラリが既に作られていたこともあって、それを流用できる利点がありました。 しかしXML形式は可読性が悪い、タグが多く手続きが面倒、文字が多い分送受信コストが高いなどの理由によって次第にJSONフォーマットに置き換わるようになってきます。JSONはJavaScript Object Notationの略で軽量なデータ記述言語になります。JavaScriptとついている通り、JavaScriptから簡単に扱えるのが特徴です。また、現在では殆どのプログラミング言語においてJSONフォーマットを扱うライブラリがリリースされています。 JSONフォーマットでデータを送受信する利点として扱いやすさもありますが、Webブラウザ、つまりJavaScriptからWeb APIを扱いたいというニーズに応えられるというのがあります。当時のWebブラウザでは異なるドメインのサイトにアクセスする際にセキュリティ上の問題があったため、JSONPと呼ばれる回避方法が人気を集めました。ただしJSONPではGETメソッドしか扱えない、現在はCORSの設定を行って外部からも扱えるようにするケースが増えています。CORSはCross-origin resource sharingの略で、クロスドメインにおけるデータ授受の指定になります。 マッシュアップサービスの登場 Web APIが出始めるのに合わせて出てきたのがマッシュアップと呼ばれるサービスです。マッシュアップとは元々音楽用語で複数の音楽をミックスして別な音楽を作り出すものになります。つまりWeb API同士を組み合わせることで別な価値を生み出すというのがマッシュアップになります。 例えば地図サービスと不動産サービスのWeb APIを組み合わせたり、天気と音楽など一見すると関係がないようなサービスも組み合わせることで新しい価値を見いだすことができます。そうしたマッシュアップサービスは膨大なデータを手軽に扱うことができ、本体のサービス側では提供が難しい（ライバル同士のサービスを合わせるなど）場合もあり、注目を集めました。 マッシュアップサービスの例（ 旅行アシストサイト MyPlan マイプラン - 都道府県・お城・世界遺産の写真から旅行計画を作成 RESTfulの台頭 Rubyで作られたフレームワーク、Ruby on Railsが提唱したのがRESTfulでした。RESTとはWebなどで使われるソフトウェアアーキテクチャのことですが、そのRESTの原則に従うシステムをRESTfulと呼びます。例えばユーザ（user）について操作するWeb APIを考えた場合、 # メソッド # パス POST /users # 新規作成 GET /users # ユーザ一覧の取得 GET /users/1 # ユーザID = 1のユーザ情報を取得 PUT /users/1 # ユーザID = 1のユーザ情報を更新 DELETE /users/1 # ユーザID = 1のユーザ情報を削除 といった形でHTTPメソッドとパスで何のオブジェクトに対する何の操作かが明確になります。さらに送受信にJSONを用いる場合は、 POST /users.json GET /users.json GET /users/1.json PUT /users/1.json DELETE /users/1.json といった形になります。Ruby on Railsが標準でRESTfulに則って作られていたため、開発者にとってどの機能が呼ばれているかが分かりやすく、Web API利用者にとっても使いたい機能が使いやすいという利点もあり、現在数多くのWeb APIはRESTfulに提供されています。 Web APIがサービスを進化させる TwitterがWeb APIのあり方を大きく変えたと言えます。それまで本体のWebサービスがある中で付随的にリリースされていたのがWeb APIでした。しかしTwitterの場合、公式サービスは機能があまり多くなく、かつWeb APIでほぼ全てのTwitterの機能が使えるようになっています。そのため開発者はTwitterのWeb APIを使い、数多くのクライアントソフトウェアや関連サービスを生み出していきました。これらはTwitterの成長を支える大きな力になったと言えるでしょう。 同様にFacebookのように自社で抱える巨大なユーザベースを外部に公開し、結果的にFacebookを成長させるというモデルがあります。この場合、Web APIにおける認証が大きな鍵になっていました。そこでFacebookはOAuthと呼ばれる仕組みを使い、ユーザ自身にどのデータを開発者に渡して良いかをコンロトールできる方法を採用しました。 アプリの世界 Web APIが爆発的に広がるきっかけになったのがスマートフォンアプリではないかと思います。スマートフォンアプリはそれ単体で使われるものは多くなく、何らかの形でインターネット上のサーバとデータの送受信を行っています。そうした時にサーバ側はWeb APIを用意し、アプリからはWeb APIを呼び出します。一般的に外部の開発者に向けて公開されているものがWeb APIと思われますが、こういったそのアプリ向けだけの専用かつ非公開なWeb APIはとても数多く存在します。 また、アプリビジネスに乗る形で作られている各種SDK（広告配信、mBaaS、アクセス解析系など）もWeb APIを使ってアプリとデータの送受信を行っています。これらはWeb APIというURLではなく、SDK（Software Development Kit）という形でラッピングして提供されています。そのため開発者はWeb APIを意識せずにその機能が使えるようになっています。 今後はどうなるのか Web APIは新しいWebサービス、アプリを作る上で欠かせない存在になっています。また、これまではコンシューマがホビー用途で使うことが多かったのですが、多くの企業がサービス間連携を行う際にWeb APIを利用するようになっています。 つまりWeb APIは開発者の間においては当たり前の存在になってきたと言えるでしょう。それに伴い、ただWeb APIを公開したくらいでは開発者の目を引けなくなっています。そのため関連ライブラリやSDKの提供、分かりやすいドキュメント、デモなどを見せる必要があるでしょう。 そして何よりWeb API自体の魅力が問われるようになっています。そのWeb APIを使うことでどういったサービスが作れるのか、その未来を感じさせることが重要になっているのではないでしょうか。

NTTコミュニケーションズの緒方です。 開発者ブログでは、APIに関する技術情報や、API利用に関するベストプラクティス、お客様ビジネスにおけるユースケースなどを紹介していきます。 まず第１回は、NTTコミュンケーションズが提供するAPIゲートウェイのご紹介です！ APIゲートウェイとは？ NTTコミュニケーションズが提供するサービスのAPIを取りまとめたゲートウェイです。 NTTコミュニケーションズでは、サービスのお申し込みから運用保守に至るまでのビジネスプロセスに関する情報の閲覧・操作やサービスの設定変更などを、企業のお客さまが利用する各種システムからダイレクトにコントロール可能とするAPIを提供しています。 サービス毎のAPI接続形式/データ書式を統一して提供したり、API利用ログの一元管理を実現するためAPIゲートウェイを開発しました。 APIゲートウェイは、NTTコミュニケーションズが提供する法人企業向けサービス契約があれば無償で利用することができます。 何ができるの？特徴は？ 1. API認証の統一 NTTコミュニケーションズが提供するAPIの認証を統一化します。 APIのリソース要求単位で認可制御ができる権限管理機能も実装していく予定（今年夏頃）です。 2. 万全なAPIセキュリティ DDoSアタックやAPIに特化したセキュリティ対策（API Callのデータ部分の解析など）を各サービス横断で導入し、安全性を確保します。 3. APIログ管理 API利用ログを参照することができます。ログは無償で過去１年分参照可能です。 ログの参照はJSONベースで出力可能なため、市販/OSSログ解析ツールなどを利用してログを管理することができます。 システム監査などでAPIログ管理機能をご活用頂く事が可能です。 4. API変換 統一された接続形式(REST API)/データ形式(JSON/XML)に変換します。 NTTコミュニケーションズが提供する複数のサービス(API)を利用したシステムを開発する際のコストを削減することができます。 利用可能なAPIは？ 2015.6現在、APIゲートウェイを経由して利用可能なAPIは以下の通りです。 詳細はAPI Docsをご確認ください。 OAuth API Business Process API API Log API Cloudn Compute API Arcstar Universal One Mobile Global M2M API 利用シーンは？ 様々な利用シーンでAPIを活用することができます。一例として、自社のサービスオーダ管理システムとNTTコミュニケーションズのAPIを連携させて、人が介在しない正確なオーダ管理を実現することができます。 また、Cloudn Compute APIを利用して、仮想サーバの各種操作を自動化することもできます。例えば仮想サーバの起動や停止、複製といったAPI操作をスクリプト化しておき、特定のイベントが発生したときにスクリプトを自動実行するといった仕組みを実現させることが可能です。 サービスのメンテナンス状況などもAPIから取得することができるので、これらを上手く活用して運用オペレーションの改善も期待できますね。 今後の予定は？ ネットワーク・クラウド・ボイス・アプリケーションの分野にてAPIの提供拡充を目指します。同時にAPIゲートウェイの機能拡充もやっていく予定です。 加えて、SDK(ライブラリ)やAPIを活用したサンプルアプリなどAPI利用ツールを整備していきます。これら利用ツールはオープンソースとして順次公開していく予定です。 第一弾として、Business Process APIを活用したデモアプリをGitHubに公開していますのでご活用ください！ Business Process API活用 サンプルWebAppコードをGitHubに公開 NTTコミュニケーションズのAPIを試用したいんだけど？ まずはデベロッパーポータル（本サイトです）からAPIキーを入手してください！ APIキーがあれば、契約中サービスで公開されているAPIを全て無償で利用できます。 APIキーの入手方法は、 こちら をご確認ください。