加藤です。 速報、という感じでなくなってしまいましたが、本日の状況をお知らせします。 本日も晴天なりで、朝から暑かったです。ここが基調講演会場のSan Jose Convension Centerです。 Keynote始まる直前です。お洒落なBGMがあり、会場を盛り上げます。このあと暗くて写真とれませんでしたが、 暗闇の中、ダンスの催しでオープニングでした。 Apigee CEO Chet Kapoorさんが登壇です。 これ結構すごい表現です!! 働くアーミーからものづくりができる人のネットワークへ。APIを介して、 合従連衡的に、自社、パートナー、エンドユーザとつながってエコシステムを形成をというメッセージかと。 いかにして働くかに。ビジネスでデジタルを活用していく。 IoT等が進めば、データの処理は人では間に合わないので、当然マシン(機械)で、インテリジェントに処理を。 Cognitive Computing & AIの世界です。それとAPIを絡める。 そして、デジタルはすべての産業をDISRUPTする、すべての産業を劇的に変えていく。決め文句として使っていきたいと思います。 最後は、EquinixさんがAPIの取り組みを紹介。詳細は別速報にてご紹介します。

加藤です。 引き続き10/12午前中の内容です。 API開発に関わるコンサル数値的な情報をお届けします。 DeloitteのAPIトレンド2015抜粋 そして、時代と共に変化するソリューションとテクノロジ。 現代のREST APIの位置付けと過去のEDIやSOAとの違いを一枚で説明。 Gartner Hypeサイクル。ちょっと斜めになってますが・・・ 世界の各地域の開発者状況。アジアとアフリカは平均年齢が27歳。日本も含まれるので、有望?! メジャーなアプリ領域において、興味深い「稼げる」分布図。モバイルAppは、B2Cなので少額金額なのは わかり易く、クラウドサービスはB2B系で高額金額に割とよっています。 IoTは、どちらかというとモバイルAppよりで少額か、まだまだ稼ぐところを見つけるのがこれからということが 言えそうです。 でこの手の世界は、デベロッパーが真の意思決定者になるべきと。これはしっくりきます。 デベロッパーによる意思決定プロセス分解。

加藤@サンノゼです。 加藤は、Masterclass How to Build Successful Developer Programsに参加しており、その速報です。 てっぺんの三角のスコープのお話です。 調査会社のEDC(Evans Data Corp.)によるUnderstanding the Development Landscape for APIsという講演です。 2021年には全世界で、2650万人規模に開発者が増加、APACが伸びてます。 IoTに関する開発はAPACと北アメリカでかなり活発化しそうな感じです。 Hot Topics セキュリティ、IoT、Big Data、 Real-time Events、Congnitive Computing & AIの5つが熱い分野でしょう、と。 開発者とのリレーションがますます必要となり、開発者とのリレーション(DevRel)に必要なことを紹介するサイトのようです。 devrelate

加藤@サンノゼです。 I Love APIs 2015が始まりました。 速報を伝えてきます。 ホテルからの眺め。田舎町であります。 入場は結構アバウトで、名前検索するだけでバッチ発行です。アメリカ的です。 会場の真上に飛行機が横切ってきます。 スタバコーヒー、ヨーグルトとかあり、参加者には助かります!!

ども、Enteprise APIs Hack-Night事務局 兼 APIゲートウェイ担当の加藤です。 10/12-10/14 サンノゼにてApigeeさん主催のI Love APIs というカンファレンスが開催されます。 I Love APIs たしか、今年で3回目?だったかと思いますが、過去の開催は加藤自身は諸都合で参加できず、今回は楽しみにしております。 Microservicesネタ、Node.js/Swaggerネタ、IoTネタ、B2B/B2CビジネスでのAPIユースケース、 Developerコミュニティ形成ネタなど、APIに関する盛りだくさんの内容が3日開催されるようですので、 まずは速報で毎日お届けしようと思います。 お楽しみにしてください。 それでは!!!

JSON Schemaを作らなければと思っても、つい面倒で先送りにしてしまいがちです。単なるシステム上だけでなく副次的に開発補助の仕組みがあれば、作る意欲もわくでしょう。そこで今回はJSON Schemaファイルを読み込んでAPIドキュメントを生成してくれるソフトウェアを紹介します。 iodocs node.jsとredisの組み合わせで動作します。JSON Schemaファイルを置いておくと、その内容をHTML上に整形して表示してくれます。Webブラウザ上から実際にAPIをコールすることもできるようになっています。 matic maticはnode.jsで作られているコマンドで、特定のフォルダとディレクトリの配置によってJSON SchemaをHTMLドキュメント化します。 JSONSchemaDocStylesheet JSON Schemaに対してXSLスタイルシートを適用することでHTML化するという試みです。今はJSONを一旦XML化し、その後XSLスタイルシートを適用します。 Prmd PrmdはRubyのライブラリで、HTMLではなくMarkdownドキュメントを出力します。JSON Schemaファイルが複数に分かれていても扱えるので、大型化しても運用しやすそうです。 Jdoc JdocもRubyのライブラリで、YAMLファイルに定義した内容からAPIドキュメントを生成できるようになっています。 Docson JSON Schemaをドキュメント化すると言うよりも、構造をHTMLを使って見やすくしてくれるツールと言った感じのソフトウェアです。Swagger向けにAPIドキュメントとして生成する機能もあります。 今回紹介したソフトウェアを使うことでAPIドキュメントを作成するコストが大幅に下がるようになります。システムとドキュメントの乖離が避けられればメンテナンスコストも低くなるでしょう。ぜひJSON Schemaを用いた開発の際に使ってみてください。

昨今、APIの重要性は高まるばかりです。プロジェクトの大小にかかわらず、APIはどこかで使われているのではないでしょうか。そこで今回はAPIの設計手順について見ていきたいと思います。APIをはじめて設計される方はもちろん、これまではなんとなく設計してきたという方もぜひご覧ください。 APIとRESTについて 最近、APIではよくREST APIや単にRESTといった単語が聞かれるようになっています。RESTとはHTTPプロトコル規格の主要著者の一人であるRoy Fielding氏が提唱したことで有名です。そのFielding氏のREST原則通りに構築されたシステムはRESTfulと呼ばれます。その経緯などの詳細は Wikipedia に譲るとして、最近は以下のように包括されているようです。 Fielding氏のRESTアーキテクチャスタイルの原則に合わせたWebサービスシステム RPCスタイルに合わせた簡易な XML+HTTP インターフェイスを採用したシステム（SOAPは使わない） 本稿では、RESTアーキテクチャスタイルの原則には沿っていません。また、APIをHTTPでのステートレスなクライアント・サーバプロトコルとして、包括的な話を進めていきます。 API定義書 API定義書は開発がはじまる前までに、たとえ資料の納品の必要がなかったとしても作成した方がいい資料です。現場サイドであらかた決めておくだけでも開発の進みやすさが違うでしょう。後から作成するなどといって先送りしてしまうと、後になって振り返りたくなってもできなくなってしまいます。 API定義書作成のベストプラクティスを上げるとすれば、コーディングとテストを行いつつ、それを定義書に落とし込めるツールになるでしょう。以下に主なツールを紹介しておきます。どれも一長一短ありますので、プロジェクトにあったツールを選定してみてください。 Swagger | The World's Most Popular Framework for APIs. mashery/iodocs r7kamura/autodoc エンドポイントの設計 パスに含めるのはどれ？ パスやクエリパラメータに含める情報については、APIを構築する言語や利用するフレームワークよって左右されてしまうことがあります。例を紹介します。以下はどちらもユーザプロファイルを取得するAPIとします。109876はユーザIDです。 // 1．IDをパスに含めるケース http://abc.com/v1/user-profile/109876 // 2．IDをクエリに含めるケース http://abc.com/v1/user-profile?id=109876 この場合、ユーザIDをシステム側がどのように取得するかによるのですが、最近の開発言語でのフレームワークでは殆どが1のパターンをルーティング処理で対応できるようになっています。実際、1の方がメソッドでの項目利用やバリデーションのフック処理などで対応しやすいと思います。 ユーザIDなど特定のIDを検索するパターンならば上記で十分です。では、ユーザ一覧を取得する場合はどうでしょうか？ここでは、10件目から20件を取得するケースとします。 // 1．IDをパスに含めるケース http://abc.com/v1/users/10/20 // 2．IDをクエリに含めるケース。offsetは何件目から取得するか、maxは取得件数を意味しています。 http://abc.com/v1/users?offset=10&max=20 1のケースはパッと見て何がしたいのか良くわかりません。このケースでは2の方が分かりやすいかと思います。 このように、操作内容によってどちらに含めるのかを考慮しましょう。基本的には、エンドポイントをデフォルトで接続した場合を考慮し、それ以外の操作は可変パラメータを渡すようにしましょう。 エンドポイントにはバージョンを含めよう APIを広く一般ユーザへ公開する場合には、バージョンを含めましょう。このバージョンを入れることで、APIの切り替えなどがスムーズになります。多くのサービスをみると、バージョンはAPIサービス名のすぐ後に入れるのが一般的なようです。たとえば次のようになります。 http://abc.com/api/v1/… http://abc.com/api/v2/… もちろん、企業向けのイントラサービスでAPIを利用する時もバージョンを入れておいた方が良いでしょう。詳しくは 適切なAPIを設計するために注意したいこと「バージョン管理、同期・非同期」 - NTT Communications Engineers' Blog を参考にしてください。 APIの命名規約など それを見て動作が想像できるか APIの命名については、アプリでメソッド名を作るときと同様に考えます。分かりやすいメソッド名は、その後の綺麗なコードを生み出します。 項目名もわかりやすく これも良くあるパターンがiとかc1などと言った1〜2文字で作成するケースです。queryをqとしたりするのはありかなと思いますが、何に使ってるのか、想像できない項目名はやめた方が良いでしょう。とはいえ、長すぎも厳禁です。長すぎるAPIは見た目も美しくありませんし、定義書を書く時やコーディングする時も面倒でしょう。 命名にあたりAPIでは名詞として複数形を利用するのが一般的になっているようです。 キャメルケースかスネークケースか、はたまたスパイナルケース？ 命名についてはいくつかの法則があります。 ケース名 例 キャメルケース userProfile スネークケース user_profile スパイナルケース user-profile これははっきりいって個人の趣味ではないかと思います。 GoogleのSEO対策として、スパイナルケース（ハイフン繋ぎ）だと単語として認識するといわれています。そこが気になるのであれば、スパイナルケースが妥当でしょう。しかしこれが本当であるかははっきりしていません。プログラマの感覚としてはGoogleがスパイナルケースしか対応しないとは考えられません。 もしJavaScriptでの規約に合わせるなら、先頭小文字のキャメルケースが良いでしょう。このように、その時の開発言語に沿って決めてもいいかと思います。 最後に API設計の導入部分を見ていきましたが、いかがだったでしょうか？最初の設計では多くのものを定義する必要があります。本文中にも記述しましたが、フロントとバックエンド側を繋ぐI/Fを早々に決めておくことが、プロジェクトの並行開発になによりも必要になります。 また、アクセスの考慮やセキュリティの問題など他にも考えるべきポイントは数多くありますが、それは今後紹介していきます。ぜひ参考にしてください！

JSONはAPIとのデータ授受に利用されるメジャーなフォーマットになっています。それだけにシステム開発の際にJSONを扱う機会も増えているでしょう。 そんな時に素のJSONファイルは見づらく、構造を見誤る可能性があります。そこで使ってみたいのが今回紹介するソフトウェアたちです。 zaach/jsonlint JSON Lintはその名の通り、JSONファイルのチェックをしてくれます。インストールは npm install jsonlint -g で、jsonlintコマンドにJSONファイルを渡すだけです。 $ jsonlint myfile.json JSONView - Chrome ウェブストア JSONViewはGoogle Chrome機能拡張で、JSONファイルを表示する際に素のテキストではなく、ハイライトと整形した状態で表示してくれます。同じような機能拡張やアドオンは各ブラウザに存在しますのでインストールしておくのが良いでしょう。 lloyd/yajl YAJLはJSONライブラリですが、YAJLをインストールすると一緒に入るJSON Verifyが便利です。これはJSONファイルが構造として合っているか検証してくれるコマンドです。手作業でJSONファイルを作った際にはまずJSON Verifyでチェックしておくと良いでしょう。 jq jqはCLIで使えるJSONパーサーで、CSSセレクタのような記述でJSONデータの絞り込みができます。JSONデータは目視では構造を見誤ることが多いので、jqを通してきちんと確認しておくのが良いでしょう。 typicode/json-server JSON ServerはJSONファイルを使ってRESTfulなWebサーバを立ち上げます。JSON Schemaではありませんが、モックデータを適用することで開発時のモックサーバとして使うこともできます。 json_pp - search.cpan.org JSON PPはCLIでJSONを整形表示してくれるソフトウェアです。ローカルにあるJSONファイルをcatで表示すると分かりづらいですが、JSON PPを使えば見やすくなります。 いかがでしょうか。JSONの普及が進んでいることもあって、多くの周辺ツールが開発されてきています。これらのツールを使うことで生産性が大きく向上するのではないでしょうか。 ぜひ皆さんの開発に役立ててください。

最近進んでいる企業におけるAPI活用情報を共有し、さらに発展させていこうという取り組みが Enterprise APIs Hack-Night です。先日、その第一回目のイベントがありました。今回はそのイベントレポートになります。 最初にEnterprise APIs Hack-Night事務局 加藤さんより開会の挨拶がありました。 ビジネスのデジタル化におけるAPI活用事例 by Apigee Japan 清水さん 最初にキーフレーズとして「あらゆるデジタルビジネスはAPIが動かしている」をあげました。「ユーザーにシームレスな体験を届けるのは難しい」とした上で、幾つかの実例を紹介されました。 シームレス体験の例 車に乗っている人のApple Watchに、処方箋を出した薬局から薬の準備ができたと通知が来ました。薬を取りに行った際に、店舗にあるプリンタで子供の写真をプリントしました。そうする内に病院で予防接種を受ける時間になり、病院に向かいました。これまでの一連の流れがある企業のシステムと統合されまして、ポイントを獲得しました。 以上のようなアクションを起こす際に、様々な企業のシステムと企業外のシステムが関係してきます。外部または内部の多くのシステムが関係してくるので、1つのアプリでさえ、スパゲッティ状態になってしまいます。スパゲッティ状態では関連するシステムのどこかに不具合が起こると、シームレスな流れが止まってしまいます。そこで、APIを管理するレイヤーを一層設けて、スパゲッティ状態を整理してアプリケーションを使いやすくするサービスを提供しています。 先に紹介した例はアメリカのWall greenの事例で、Wall greenはコンビニエンスストアと薬局が一緒になったような企業です。事例の中の「処方箋ができました」という通知は処方箋APIで動いています。もちろんAPIだけでなく、外部内部の様々なリソースで動いており、自分の体験はどこかで繋がっているとユーザーに実感してもらえるようになります。 AP通信社（独立系の非営利通信会社） ニュースを探してきて記事を書いて提供するアフィリエイト企業とのつながりを広げていきたいと考えでした。レガシーのシステムと繋げるのは難しいため、バックエンドシステムをAPI化してつながりやすくしました。外部のパートナー企業とのつながりを広げるのももちろんですが、社内のシステムBtoE（Business to Employee）も推進しています。 Salesforce (CRM大手) 社内のシステムが古くなっており、バックエンドのシステムを新しくしたいと考えていました。アプリベースのサービスを作り、CRMサービス提供企業として、自社内の業務効率を上げていきたいと考えています。社内向けのシステムを新しくするときにもAPIは使えます。 Dell 製造データ、ビジネスパートナー（再販事業者、代理店、サプライヤーなど）とのコミュニケーションを取る上でリアルタイム性に欠けているのが課題でした。APIを活用することでリアルタイム性を実現しています。バックエンドに手を入れるのはコストと時間がかかり、APIを管理するレイヤーを加えることでバックエンドを改修しています。 ベッケル社 (巨大建造物を作る建築エンジニアリング会社) API導入以前、図面の修正は事務所に戻ってしており、工事の効率が上がりませんでした。工事管理責任者にiPadを支給して、iPad上で走るアプリを自分たちで制作しています。例えばコンクリート工事の進捗を見る場合、コンクリートを埋めるときにセンサーを入れ、そこから送られてくるデータで進捗を確認する。建築現場では協力会社など多くの他社とも関わりますが、他社の人にはデータの出し分けをして、管理をしています。 質疑応答 質問：BtoEの話ですが、コストダウンのために行うのか戦略的に行うのかどちらですか。 回答：両方だと思います。まずはコストダウンです。独自アプリを作る際にAPIは適しています。最終的には外部パートナーと繋ぐ流れが見受けられます。より先端の企業は完全にAPIをパブリックにしています。APIを元に個人や企業が開発し新たなビジネスを作っていこうとしています。 質問：セキュリティ面が気になります。 回答：一番重要な点になると思います。私たちのプラットフォームも重要な機能として備えています。APIを作る上でバックエンドも安全でなければならないと思います。 APIがNTTコミュニケーションズのサービスを進化させるby NTTコミュニケーションズ　緒方 宏明 弊社の緒方が登壇しました。 通信キャリアにおけるAPI 世界的にみて通信キャリアが提供するAPIは増えてきています。 2015年現在、通信業界におけるAPI市場は500億ドル程度ですが、3年後の2018年通信業界のAPI関連の市場規模が1570億ドルになると見込まれています。 Business Process API 通信キャリアには販売代理店、SIer、法人企業、コンシューマーなどのお客さまがいます。AT&TではAPI関連収入の80%が主要代理店10社で占められているというデータもあり、キャリアにとって販売代理店は重要なお客さまの一つです。なので各通信キャリアは販売代理店が望む契約情報やサービスオーダーをAPI経由で情報取得できるBusiness Process APIをはじめに整備していきました。 通信キャリアならではの機能系API 次にネットワークやクラウドなど通信キャリアならではの機能系APIを整備しています。そして最近ではM2M/IoT、Web-RTCなど新しい分野・技術に関するAPIの拡充を進めています。 海外の主要キャリアのAPI提供状況 AT&TやOrangeなどでは、Business Process系、認証認可系、機能系APIなどのコアAPIの提供は一通り完了しています。 APIをEnterprise用途で使ってもらうために必要なこと APIの仕様ルールを統一し、社内のルールとして規定していくこと、提供するAPIをマネージメントすること、アクセス制御などセキュリティ機能を充実させることなどがあります。 APIをマネジメントすることとは 　APIをマネジメントするとは自社で複数のサービスがあってそれを提供する場合、各サービスでバラバラに管理するのではなくて、管理ツールによって一元的に管理することです。管理対象は認証、ログ、セキュリティ、アクセス権限、トラフィック制御などです。代表的な管理ツールは、この開発者ブログでも紹介しているので参考にしてください。 お客様の個々のアクセス権限管理 Enterpriseでは参照できるAPIを限定的にしたり、参照はできるが更新・削除はできないなど、きめ細やかな権限管理が必要になってきます。業務要件はお客さまによって異なります。ですのでお客さまご自身で柔軟にアクセス権限を設定できる仕組みが重要であると考えます。 情報やイベントをリアルタイムに提供する REST APIだけでなく、イベントが発生した時に自社のサービスからお客様にプッシュ通知する仕組みもEnterpriseでは必要であると考えます。通知する仕組みとして代表的な技術にWebhookがありますが、今後弊社としてもWebhookを活用したアプリケーションtoアプリケーションで情報を提供する仕組みを整備していきたいと考えています。 APIによって進化し始めているNTTコミュニケーションズのサービス 当社ビジョンの主要強化施策の一つにAPIの充実化がありまして、全社をあげてAPIの充実化に取り組んでいます。提供中のAPIはビジネスプロセス系、機能系（クラウド、ネットワーク、ボイス、アプリケーション）などがあります。 お客さまにAPIを提供する際には、APIゲートウェイで認証やデータフォーマットなどを統一化しています。APIゲートウェイは日本・アメリカ・ヨーロッパの3拠点で展開しており、グローバルシームレスに利用可能です。 近々にAPI権限管理をリリース予定（9/10リリースしました）で、さらに安全に便利で使いやすく、今後もNTT Com APIは進化していきますので宜しくお願いします。 IoT/M2M分野におけるWeb APIの使い方とデモ by MOONGIFT　中津川 篤司 さん IoTの特徴 IoTとは Internet of Thingsの略。ネットワークが根幹にあります。 M2Mとは Machine to Machineの略。マシンとマシンをつなぐというよりは、クラウドを挟んで、MtoCtoMの方が意味があるのではと思います。 ネットワーク 無線なのか有線なのか？近距離なのか中距離なのか？ハブ型なのか単体なのか？それによってネットワークの種類を設定することがIoTの基本です。 また、ネットワークの別の観点でプロトコルがあります。とにかくデータ量が多いので、データ量を減らして、双方向性で信頼性を高くしたいです。UDPよりPCPが使われます。 MQTTとは Hub-Sub型、httpに比べてヘッダのデータ量が少なく（2バイト）、N対Nでネットの送受信ができます。中間にブローカーがおり、データを出力するパブリッシャー、データを受け取るサブスクライバーがいます。パブリッシャーは同時にサブスクライバーになることができます。パブリッシャー、サブスクライバーはトピックを持っています。例えば、cat1にパブリッシャーが発信するとcat1を購読している人だけが受け取ることができます。 IoTデバイスの特徴 低消費電力。小さい。遠隔地に置く。安価。 IoTにおけるweb APIとは ビッグデータ型 デバイスのIDとトークンを持たせて、センサーからのデータをネットワーク上に投げるのみです。データがあまりにも膨大になりすぎてしまう恐れがあるので、閾値判定程度は行えます。また、一時間に一度だけデータをアップしたいという要望がよくありますが、一度にアップするとサーバが落ちたり、遅延が発生したりします。グループごとに起動するタイミングをずらすようにして対応します。基本はget/postでエンドポイントが1つです。httpsや MQTTSを使います。デバイスをトークンにかませます。 スマートフォン型 Beacon系のデバイス。デバイスは情報を発信するだけです。動いているかどうかの生存確認が困難で、検証が難しいです。スマートフォンにアプリを入れなきゃいけないのが厄介な点です。最近、山手線アプリが行っていたサービスで、電車の中でアプリを立ち上げるとポケモンがゲットできるものがありました。乗っ取りの恐れがありますので、クリティカルな要件では注意が必要です。https・outh・プッシュ通知などが使えます。 ホームオートメーション 最近よく耳にするスマートホームという言葉には2つの意味があります 地域や家庭内のエネルギーを最適制御する住宅。 家電などを情報化する。 今回は2の意味になります。 ドアを開けたら家の明かりがつくなど、ホームオートメーションの多くは自宅がトリガーになります。そのため、ネットワークは使いますがインターネットを使いません。一つ、インターネットを使うものが、おじいちゃん・おばあちゃんの状態を遠隔で監視して、閾値を超える行動があると息子・娘のところへプッシュ通知を飛ばす高齢者の安否確認システムではないかと思います。 音声による制御 Rasberry Piにjulius（音声認識エンジン）を入れます。マイクに音声を入れて、Rasberry Piでテキスト解析して、内容によってRiキット（赤外線通信を出すデバイス）で照明を消すことができます。 MQTTで合成音声チャット speakAPIをつかって、Rasberry PiとChromeで会話することができます。一人でしりとりも出来ます（笑）。 ライトニングトーク 懇親会で行われたライトニングトークをご紹介します。 1. レガシーなアプリにAPIを実装 請求書発行のクラウドサービスの会社でWeb APIを実装した際に苦労しました。Seasor2を拡張し、主要な機能のみ対応しました。参加されている方のご意見を聞きたいです。 2. Enterprise × APIs API利用者はデザイン思考とビジネス思考が必要です。Enterprise APIは法人同士が使うAPIと考えています。企業間を結ぶAPIビジネスをやりたいと思っています。コミュニティ活動でコミュニティをつなぐことは自分の思考にもマッチしています。 3. 5分でわかるWeb RTC Web RTCとはリアルタイムコミュニケーションをソフトウェアエンジニアが自由に使えるものです。Webサイトやアプリに組み込みができ、コミュニケーションアプリや家電・IoTなどで使えます。 4. APIをEnterprise用途で使うために APIをEnterprise用途で使うために有用なソフトNode-RED( http://nodered.org/ )の紹介です。IoT用と言われていますが、様々なAPIを実行することができます。 5. APIとマーケティング API MeetupでUnityとPaypalの連携デモを行ったら、バズりました。せっかくのテスト環境をハッカソンなどで使うことで、思わぬ発見があります。 6. NTTネットワークサービスシステム研究所の取り組み 重厚長大でなく、組み合わせでつくります。アーキテクチャ、既存のものをどう出していくか、仕様の統一をすることが必要です。APIはインターフェースを使ってつくります。APIは叩いてみないとわからないので、叩いてみます。 次回は12月04日を予定しています。皆さまお誘い合わせの上、ぜひご参加ください！また、 Enterprise APIs Hack-NightはSlackにてオンラインコミュニティを提供 しています。ぜひこちらもご参加ください！ Enterprise APIs Hack-Night - connpass

既にWebシステムが稼働している中でREST APIを追加するというのは工数がかかります。そこで使える手段としては、 APIゲートウェイ製品・サービスの利用 RESTフレームワークの導入 という選択肢が考えられます。今回はその中でもRESTフレームワークを導入するのに使えるフレームワークを紹介します。 WordPress › WordPress REST API (Version 2) « WordPress Plugins WordPress REST APIをインストールすることでWordPressにREST APIを追加することができます。WordPressをCMSとしてアプリから使ったり、フィードとは違って他のシステムからデータ投入もできます。元々WordPressではXML-RPCがありますが、ライブラリもそれほど多くないのでWordPress REST APIのが使いやすいでしょう。 cookpad/garage GarageはRailsアプリケーションに組み込んで使います。リード/ライトアクセス制御であったり、簡単にRESTful APIを実装できるようになっています。ロジックは自分で書くのでより実践的なAPIが作れるようです。 API Guide | restify node.jsアプリケーションにREST APIを追加するモジュールです。node.js向けWebアプリケーションフレームワークというとExpressが有名ですが、restifyはAPIに特化しているのがポイントです。 Django REST framework Djangoで作ったシステムに手早くREST APIを組み込めるのがDjango REST frameworkです。既存のモデルをそのままAPI化する時に便利そうです。バージョニング、ページネーション、フィルターなどカスタマイズする機能もあります。 Tastypie - RESTful APIs for Django TastypieもDjangoにRESTfulなAPIを追加するライブラリです。GET/POST/PUT/DELETE/PATCHをすべてサポートしています。やり取りするデータフォーマットとしてJSON/XML/YAML/bplistがサポートされています。 dingo/api PHPのフレームワーク、LaravelにREST APIを手軽に追加できるライブラリです。REST APIだけでなく、OAuth 2.0の実装も可能で、JSON以外のフォーマットにも対応しています。API Blueprint対応のドキュメントも生成します。 Luracast/Restler 任意のPHPアプリケーション向けにRESTful APIを提供します。OAuth 2.0もプラグインで提供されています。APIの利用制限機能、JSONPサポートであったり、入出力フォーマットにJSON/XML/Yaml/Amf/Plistが選択できます。 RESTフレームワークは著名なソフトウェア（WordPressなど）やフレームワークごとに存在するようです。使っているフレームワークに合わせてライブラリの選択をすれば、WebシステムのAPI対応も素早くできるのではないでしょうか。

2015年9月10日に、NTT Com APIゲートウェイ 権限管理機能をリリースしました。 本機能を利用することで、お客さまご自身でNTT Com APIに対するアクセス制御が設定できます。 アクセス制御は以下の通りきめ細かに設定できますので、お客さま個々の業務用件を満たす柔軟なアクセス制御が可能となります。 API単位 アクセス権限の対象として複数のAPIを指定することができます。さらに詳細な設定としてREST APIのメソッド(GET/POST/PUT/DELETE)や、リソースパスも指定することが可能です。 IPアドレス単位 お客様が利用されるアクセス元IPアドレスを複数指定することができます。 任意のデータ単位 JSONペイロードやヘッダのうち、利用を許可したいデータをキー、バリューの組み合わせにて指定することができます。これによって、契約情報やサービス名などを個別に権限設定することで、より強固なアクセス制御を実施することが可能です。 権限管理機能の操作手順 権限管理機能の操作手順は以下の通りです。 ユーザ・グループを作成する 権限を作成する グループと権限を紐づける なお、上記操作は「権限管理(IAM)API」を使います。詳細は API Docs をご確認ください。 実際に権限管理機能を使ってみる それでは実際に権限管理機能を使ってみましょう。 今回はBusiness Process APIに対して様々な権限管理を設定してみます。 Business Process APIとは、NTT Com各種サービスのビジネスプロセスに関する情報提供や、操作を可能とするAPIです。契約情報API、サービスオーダーAPI、チケットAPI、メンテナンスAPIがあります。 契約情報APIにアクセスできるようにする まずはBusiness Process APIの一つである契約情報APIにアクセスできるユーザを作成してみます。 手順は以下の通りです。 準備 権限管理機能を利用するには、ビジネスポータルからお申込頂くデベロッパポータルのアカウント（以降、権限管理者）が必要です。もしお持ちでない方は こちら からお申込みください。 API利用のための認証情報の取得 以下の通り権限管理者でOAuth APIにアクセスし、accessTokenを取得します。今回はhttpieというツールを使ってAPIにアクセスしています。 リクエスト 権限管理者のclientIdとclientSecretを入力してaccessTokenを取得します。clientIdとclientSecretはデベロッパポータルから確認できます。 http -v POST https://api.ntt.com/v1/oauth/accesstokens grantType=client_credentials clientId=[権限管理者のConsumerKey] clientSecret=[権限管理者のConsumerSecret] レスポンス 以下のようなレスポンスが返ってきますので、accessTokenをメモしておきます。 { "accessToken": "[権限管理者のaccessToken]", "expiresIn": "86399", "issuedAt": "1441957092928", "scope": "READ WRITE", "tokenType": "BearerToken" } ユーザを作成する 契約情報APIにアクセスできるユーザを、権限管理APIを使って作成します。この操作も権限管理者で実施してください。 ユーザ(userA@example.com)の作成 リクエスト http -v POST https://api.ntt.com/v1/iam/users "Authorization: Bearer [権限管理者のaccessToken]" \ mail=userA@example.com \ portalUse=1 \ # デベロッパポータルの利用を許可する場合は"1"を入力 password=****** \ distributorFlag=0 レスポンス 正常にユーザが作成されると、以下のようなレスポンスが返ります。 { "users": [ { "consumerKey": "[userAのConsumerKey]", "consumerSecret": "[userAのConsumerSecret]", "distributorFlag": 0, "mail": "userA@example.com", "portalUse": 1, "uuid": "[userAのuuid]" } ] } 以上でユーザ作成は完了です グループを作成する 次にユーザが所属するグループを作成します。この操作も管理者権限で実施してください。 グループ（groupA）の作成 リクエスト http -v POST https://api.ntt.com/v1/iam/groups "Authorization: Bearer [権限管理者のaccessToken]" \ groupName=groupA レスポンス { "groups": [ { "groupName": "groupA", "roles": [], "uuid": "[groupAのuuid]" } ] } ユーザをグループに紐づける 作成が終わったら、ユーザをグループに紐付けます。複数のユーザを同じグループに紐づけることもできます。 リクエスト groupIdとuserIdは上記手順で取得したuuidを指定してください。 http -v PUT https://api.ntt.com/v1/iam/groups/[groupAのuuid]/users/[userAのuuid] "Authorization: Bearer[権限管理者のaccessToken]" レスポンス { "groups": [ { "users": [ { "userId": "[userAのuuid]" } ], "uuid": "[groupAのuuid]" } ] } 権限を作成する いよいよ権限の作成です。 今回はBusiness Process APIで提供されるAPIのうち、契約情報APIだけアクセスできる権限(roleA)を作成します。 なお権限付与はホワイトリスト形式で指定します。デフォルトでALL DENYになっているので、リソースに対して許可したい値を権限に追加していく形になります。全て許可したい場合はワイルドカードを指定してください。 なお、本操作も権限管理者で実施してください。 リクエスト http -v POST https://api.ntt.com/v1/iam/roles "Authorization: Bearer [権限管理者のaccessToken]" \ resources:='[basePath:=/v1/business-process, ipAddress:=*, path:=/contracts, verb:=*, "ipAddress": "*"]'\ 　　　roleName:=roleA レスポンス { "roles": [ { "resources": [ { "basePath": "/v1/business-process", "ipAddress": "*", "path": "/contracts", "verb": "*" } ], "roleName": "roleA", "uuid": "[roleAのuuid]" } ] } グループと権限を紐づける 最後にグループと権限を紐付けます。この設定によってユーザは契約情報APIにアクセスできるようになります。 リクエスト http -v PUT https://api.ntt.com/v1/iam/groups/[groupAのuuid]/roles/[roleAのuuid] "Authorization: Bearer[権限管理者のaccessToken]" 以上で設定完了です。ここまで約５分！ 契約情報APIにアクセスしてみる それでは作成したユーザで契約情報APIにアクセスしてみます。 ユーザでOAuth認証を行う リクエスト ここからは作成したユーザでアクセスしてください。 http -v POST https://api.ntt.com/v1/oauth/accesstokens grantType=client_credentials clientId=[userAのConsumerKey] clientSecret=[userAのConsumerSecret] レスポンス { "accessToken": "[userAのACCESS_TOKEN]", "expiresIn": "86399", "issuedAt": "1441869735683", "scope": "READ WRITE", "tokenType": "BearerToken" } 契約情報を参照してみる リクエスト（ネットワークサービス"UNO"の例） http -v GET https://api.ntt.com/v1/business-process/contracts?serviceName=uno" "Authorization: Bearer [userAのACCESS_TOKEN]" レスポンス { "items": [ { "accessLineSet": , "accountId": *********, "cRef": *********, "contractId": "N********", "distinguishName": *********, "internalContractId": *********, "mainBack": *********, "mainBackGroup": *********, "optionType": *********, "serviceName": "*********", "serviceStatus": *********, "site": *********, "vpnGroupId": "V*******" }, { "accessLineSet": *********, 以下略 同様に他のサービスオーダーを確認したいときは、contracts?serviceName=****に確認したいサービス名を入力して参照してください。 特定サービスの契約情報だけ参照できるようにする 上に書いた手順で、契約情報APIにアクセスし新規契約情報を登録したり参照したりすることができるユーザを作成できました。 しかしながら実際の業務では、特定のサービスに関する契約情報だけを参照させたいケースや、参照はできるが更新や削除はできないようにしたいケースなどがあると思います。 このようなケースにも柔軟に対応できることが、今回の権限管理機能の特徴でもあります。 そこで次は、特定サービス(UNO)の契約情報だけ参照できる（更新や削除はできない）ように権限を変更してみたいと思います。 権限（ロール）を変更する 先ほど作成した権限(roleA)を以下の通り変更します。 serviceNameに、unoを指定 verbをGET(参照)のみに変更 リクエスト http -v PUT https://api.ntt.com/v1/iam/roles/[roleAのuuid] "Authorization: Bearer [権限管理者のACCESS_TOKEN]" roleName=roleA resources:='[{"basePath":"/v1/business-process","path":"/contracts", "serviceName":"uno", "verb":"GET", "ipAddress":"*"}]' レスポンス { "roles": [ { "resources": [ { "basePath": "/v1/business-process", "ipAddress": "*", "path": "/contracts", "serviceName": "uno", "verb": "GET" } ], "roleName": "roleA", "uuid": "[roleAのuuid]" } ] } UNO以外の契約情報APIにアクセスしてみる レスポンス { "errorCode": "403", "errorMessage": "You do not have permission to the API." } このように、パーミッションエラーが表示されアクセスできないように制御できます。 契約情報API以外のAPIへもアクセスできるようにする 次に、契約情報以外のAPIへもアクセスできるように設定してみます。 追加するAPIはサービスオーダーAPIです。 今回は契約情報APIとサービスオーダーAPIにアクセスできるようにする(=or条件)ため、権限(roleA)に新たなresourcesを追加するように設定します。 グループと権限の関係性については API Docs に詳細を記載してありますのでご確認ください。 リクエスト http -v PUT https://api.ntt.com/v1/iam/roles/[roleAのuuid] "Authorization: Bearer [権限管理者のaccessToken]" roleName=roleA resources:='[{"basePath":"/v1/business-process","path":"/contracts", "serviceName":"uno","verb":"GET"}, {"basePath":"/v1/business-process","path":"/service-orders", "serviceName":"*", "verb":"*"}]' レスポンス { "roles": [ { "resources": [ { "basePath": "/v1/business-process", "path": "/contracts", "serviceName": "uno", "verb": "GET" }, { "basePath": "/v1/business-process", "path": "/service-orders", "serviceName": "*", "verb": "*" } ], "roleName": "roleA", "uuid": "[roleAのuuid]" } ] } サービスオーダーAPIへアクセスする それでは追加したサービスオーダーAPIへアクセスしてみます。 リクエスト http -v GET https://api.ntt.com/v1/business-process/service-orders?serviceName=uno" "Authorization: Bearer [userAのACCESS_TOKEN]" レスポンス { "items": [ { 　"contractId":"N********", 　"serviceName":"********", 　"orderType":1, 　"offerPlanDate":"********", 　"orderStatus":1 　"orderRequestNum":"************" } ] "resultCount":1 } このようにサービスオーダーAPIにもアクセスできるようになりました。 特定の場所からだけ契約情報APIにアクセスできるようにする 利用するユーザによってアクセスできるリソースを限定することができましたが、現在の設定ではどこからでも契約情報APIやサービスオーダーAPIにアクセスできてしまいます。外出先や自宅などからはリソースにアクセスさせたくないケースもあるかと思います。 次は社内など特定の場所からだけ契約情報APIにアクセスできるように設定してみます。 新たな権限(roleB)を作成する リクエスト http -v POST https://api.ntt.com/v1/iam/roles "Authorization: Bearer [権限管理者のaccessToken]" roleName=roleB resources:='[{"ipAddress":"192.168.1.100"}]' レスポンス { "roles": [ { "resources": [ { "ipAddress": "192.168.1.100" } ], "roleName": "roleB", "uuid": "[roleBのuuid]" } ] } 権限(roleB)をグループに紐付ける リクエスト http -v PUT https://api.ntt.com/v1/iam/groups/[groupAのuuid]/roles/[roleBのuuid] "Authorization: Bearer [権限管理者のaccessToken]" レスポンス { "groups": [ { "groupName": "groupA", "roles": [ { "roleId": "[roleAのuuid]" }, { "roleId": "[roleBのuuid]" } ], "uuid": "[groupAのuuid]" } ] } 許可されていない場所からAPIにアクセスすると、パーミッションエラーが表示されます。 { "errorCode": "403", "errorMessage": "You do not have permission to the API." } 今回はBusiness Process APIに対して権限設定を実施してみました。 次回以降、弊社のクラウドサービスやネットワークサービスにおける権限管理の設定例を随時紹介していく予定です。お楽しみに。

JSON Schemaはバリデーションにも使える構造になっていますが、今回はその逆でJSON Schemaを使ってREST APIなサーバを立ち上げるライブラリを紹介します。これらを使えばAPIが開発段階であってもJSON Schemaを使ってクライアントアプリやサービスの開発ができるようになります。 mingderwang/ginger Go製のライブラリで、JSON SchemaからRESTfulなAPIサーバを立ち上げます。 dorante node.js製のライブラリでJSON Schemaファイルを使ってサーバを立ち上げます。コードを書くので細かくカスタマイズできます。 interagent/committee インストール後、committee-stubコマンドが使えるようになります。後はJSON Schemaファイルを渡せばサーバが立ち上がります。 retro/apitizer サーバを立てる訳ではなく、JSON Schemaを使ってクライアントサイドのJavaScriptでモックデータを返却してくれます。 r7kamura/rack-json_schema JSON Schemaファイルを指定することでモックサーバを立ち上げてくれます。バリデーションチェックなどの機能も入っています。 元々XML Schemaが面倒でJSONがもてはやされるようになった歴史もあり、JSON Schemaを作るモチベーションはなかなか働きづらいものです。そのためにもJSON Schemaを徹底的に使い倒せるライブラリの存在が欠かせません。 その結果としてドキュメントやスタブサーバ（モックサーバ）ができたり、バリデーションなどの開発工数が減るならばJSON Schemaを導入する意味が出るでしょう。ぜひ使ってみてください。

APIのデファクトスタンダードなフォーマットの一つになっているのがJSONです。XMLに比べるとシンプルな構造ですが、括弧が多いために人にとっては複雑な構造になるととても見づらくなります。そのためデータの場所を読み違えてエラーを起こしてしまうこともあります。 それを防げるのがJSONを見やすく加工してくれるビューワーであったり、データをメンテナンスできるエディタです。今回はオープンソース・ソフトウェアを中心に紹介します。 JSONMate - JSON editor, inspector and beautifier JSONを貼り付けたり、外部のAPIから取得してビジュアル化できます（取得はJSONPのみ対応しています）。そしてエディタ部で修正を加えると、その結果がテキストのJSON側にも反映されます。 JSON Editor リッチなJSONエディタです。スキーマと組み合わせて使う仕組みになっていて、カラーピッカーを定義したり、数値入力に限定するといったことができます。 JSON Editor Online - view, edit and format JSON online シンプルなJSONエディタです。テキストとビジュアル化されたJSONのどちらかを修正後、ボタンを押してもう片方に反映する仕組みになっています。 JSON Viewer - Home Windows用のJSONビューワーです。基本的には閲覧用ですが、Visual StudioやFiddler 2と連携できるのが特徴になります。 HULK 左右ではなく上下にテキスト部とエディタ部が分かれたソフトウェアです。キーと値を自由に追加、削除できるようになっています。 JSONView :: Add-ons for Firefox FirefoxでJSONを見やすく表示してくれるアドオンです。同様に Google Chromeでも同じような機能拡張 JSON Viewer があります。API開発時にはこの手のアドオンを入れておくのが良いでしょう。 JSONLint - The JSON Validator JSONは手作業ではなくシステム側で生成することが多いかと思いますが、時々手作業で作成したり修正を加えることがあります。その結果としてエラーを起こすケースもあります。そうした時にはJSONLintを使うことでJSONとしてそもそも正しいのかどうか検証できます。 jq jqは編集機能はありませんが、指定した項目だけを出力したり、配列の一部だけを出力と言ったようなCSSセレクタ的な指定ができるようになっています。既に手元にJSONファイルがある場合、jqを使うと構造が分かりやすくなるでしょう。 やはりJSONはJavaScript系だけあってWebベースのものが多いように思います。特に整形に加えてハイライトもしてくれるビューワーはブラウザにインストールしておくと重宝するはずです。 JSONを使うのに慣れるとシステム外のデータでもJSONで書いて保存しておきたくなることがあります。そうした時にはエディタを使って操作してみてください。

Webサイトやアプリなどを彩る上で欠かせない存在が画像です。最近では高解像度化、多くの画面サイズのデバイスが増えており、画像もそれぞれに合わせて準備する必要があります。それは大きなコストになるでしょう。 そこで使ってみたいのが画像加工を行ってくれるAPIです。パラメータで指定した通りにリサイズしたり、クロップするなど様々な機能を備えています。 Cloudinary - Cloud image service, upload, storage & CDN 画像を変換するだけでなく、クラウド上に保存してくれる機能も備えています。配信はCDNを使っており、高速配信が可能です。各種プログラミング言語向けにライブラリも用意されています。 http://res.cloudinary.com/demo/image/upload/w_133,h_133,c_thumb,g_face/bike.jpg のように指定することで顔を中心にクロップしてくれる機能もあります。 Image Resize API | Embedly パラメータの中で元画像のURLを指定するタイプの画像加工APIです。元画像がなかった場合のURLを指定することもできるのでシステムで自動化するのに向いているのではないでしょうか。 http://i.embed.ly/1/display/resize?height=200&width=400&url=http%3A%2F%2Ffarm8.staticflickr.com%2F7196%2F7070072209_d1f393c797_b.jpg&key=xxxxx のように指定します。 imgix • Real-time image processing and image CDN 画像のサイズを変更するだけでなく、切り抜き、ぼかし、ウォーターマーク、回転など様々な加工ができます。さらにPNG/GIF/JPEG/WebPなどの画像フォーマット変換もサポートしており、各デバイスごとに最適な画像を配信する機能があります。 Kraken Image Optimizer · Kraken.io 画像のサイズ変更の他、独自技術による最適化処理を行えます。場合によっては1/4程度までサイズが軽減することがあります。これにより表示速度の高速化が考えられます。 ImageShack - Imagizer Resize 画像に対してInstagramのようなフィルタをかけることができます。フィルタをランダムに適用することで写真の印象を大きく変えられるのではないでしょうか。 Mobify.js Documentation Mobifyはモバイル向けのWebサイト最適化技術を提供していますので、画像変換についてもターゲットはモバイル、タブレットデバイス向けになります。リサイズやWebPを使ったフォーマット変換も行います。 Free Online Picture Resizer - Crop and Resize photos, images, or pictures online for FREE! リサイズ、クロップが提供されています。さらにバッジ型にしたり、油絵風、ポラロイド風加工を指定することができます。 Resize Pictures Online - FREE with a developer API 画像のリサイズ、クロップ、ぼかし、グレースケール、フォーマット変換の機能があります。 10枚程度の画像であれば手作業で変換しても苦ではありませんが、ユーザが自由にアップロードできる場合などはシステム上で画像変換が必要になるでしょう。とはいえ膨大な枚数の画像変換はシステム負荷が高いです。 そこでこうしたAPIを使うことでシステムの複雑性を解消したり、実装コストを大幅に下げることができます。ぜひ有効に使っていきたいですね。

REST APIを利用する場合、WebブラウザだけではGET/POSTメソッドまでしかサポートされていません。そのためPUT/DELETEといったメソッドのテストは別途コードを組む必要があります。 そこで使いたいのがRESTクライアントソフトウェアです。Webブラウザ機能拡張として用意されているものもありますので手軽に使えるはずです。 Advanced REST client - Chrome ウェブストア Chromeアプリとして提供されるソフトウェアです。GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONSなどのメソッドがサポートされています。 RESTClient, a debugger for RESTful web services. :: Add-ons for Firefox FirefoxアドオンのRESTクライアントです。レスポンスヘッダーなどが綺麗にハイライトされていて分かりやすいです。 wiztools/rest-client Javaで作られたRESTクライアントで、WindowsやMac OSX、Linuxと幅広く動作します。ブラウザやOSに依存したくない場合は良い選択肢でしょう。 eXeries - XML REST Web Service API Developer Tools WordPressなどで使われているAtom Publishing Protocolを使った開発の支援ツールです。エディタとしても利用でき、ブログエディタ的に使うこともできます。 Edentech/RESTtest Mac OSX用のRESTクライアントです。シンプルな画面構成なので機能は多くありませんが殆どの場合これで十分ではないでしょうか。 Postman | Supercharge your API workflow Chromeアプリとして提供されるRESTクライアントです。モダンなUIになっているのが特徴です。 Storm - Home 最後はRESTではなくWebサービスクライアントです。WSDLファイルを指定することでWebサービスをテストできます。 いかがでしょうか。RESTクライアントを用意しておけばAPIを使った開発がとてもスムーズになります。また、単に使うだけでなくAPIを作る側としても目に見える形でテストする際に今回紹介したソフトウェアは役立つことでしょう。 ぜひ皆さんのAPI開発に役立ててください。

今回は「お盆特集」として、閑話休題で面白サイトを紹介します。APIを使った開発、またはAPI自体を開発したことがある人なら誰もが理解してくれるであろう {"apis":"the joy"} というサイトを紹介します。ぜひ「ああ〜あるある」と思ってもらえれば。 今回はその中から幾つかをピックアップして紹介します。 When I try the code sample on the API doc APIドキュメントに書かれたサンプルコードを実行したら… APIプロバイダはうまくいく、として提示しているコードが全く動かない…実にあるあるですね。 When I integrate OAuth at first attempt はじめてOAuthを組み込んだ時… 何かよく分からないけれど（もっと簡単な方法もありそうだけど）、すごいことが起こって結果うまくいってしまったといった感じでしょうか。 When I make a live demo of my API in a conference カンファレンス向けにAPIのライブデモを作った時… 慎重に作ったはずなのに、ライブデモの時に限って動かない。本当によくありますよね。無言でコードの修正をはじめられたりすると、見ているこっちが冷や冷やしてしまいます。 When I use an API not reading the Terms of Service 利用規約を読まずにAPIを使った場合… これは実に怖い。突然利用規約が変更されたり、違反する使い方をしていて問題になったといった話も聞かれます。利用規約はちゃんと読むようにしましょう。 他にもたくさんのネタがあります。この方自身がAPIの利用、開発ともに行われてきたからこそ分かるネタと言えそうです。APIを使っていてストレスを感じたらぜひ{"apis":"the joy"}を見て共感&発散してください。 個人的によくあると感じるのは似たような機能を提供するのにAPIが2つに分かれている（追加開発の結果なんだろうな）とか、最初と後の方でドキュメントの粒度が異なる（通常、後の方が薄くなっていく）といったところでしょうか。 {"apis":"the joy"}

エンタープライズにおけるAPI活用における利点、課題はどこにあるのか。今回はその実情を知ってもらうべくAPIゲートウェイを開発している加藤さんにインタビューを行いました。聞き手はMOONGIFTの中津川です。 3年前から企画していたAPIゲートウェイとは？ Web API（以下API）が普及して10年くらい経ち、ここ数年ビジネスにおいてもAPIを公開することでサービスの利用率や競争力を高めていこうという動きが活発化しています。私たちNTTコミュニケーションズとしても自社サービスをAPI化し、利用を広めていこうと進めています。そんな中、各サービスごとにばらばらにAPIを出すのではなく、標準化や管理を統一して使いやすいAPIを提供していこうというのがAPIゲートウェイになります。ここ1、2年で同様のサービスが幾つか出てきています。 約3年前に企画して技術検証とプロジェクトの立ち上げ、そして今年の4月から正式に公開したサービスになります。技術検証はあらかじめ進めていたので実際の開発期間は半年くらいになります。 NTT Communications APIs | NTT Communications Developer Portal すでに海外でははじまっているAPI管理サービス AT&TやVerizonといったキャリアが既に動いています。キャリアで進んでいるのは主に3つの理由があります。 持っているサービスが幅広い 共通化したインタフェースを通して提供することで顧客ロイヤリティを向上する 多岐に渡る部門において技術的なクッションになる といった理由から生まれているようです。 APIを管理する仕組みがない場合に起こる問題ですが、例えばAPIではありませんがNTTコミュニケーションズにおいて社内標準がないままに各部署がスマホアプリを自由に開発した時期があります。その結果として全体の品質やインタフェースの統一感がなく、利用者を混乱させてしまう状況にありました。同じようなことがAPIにおいても起こらないために、2つの施策を考えています。 APIゲートウェイ APIチェックリスト がそうです。 単に作るだけでなく、どう作るかを規程するAPIチェックリスト 技術力があればAPIを作ることはできます。ただ、どう作るのがベストであるのかは人によって判断が分かれるところです。そこでインタフェースやセキュリティ、データフォーマットなどについての統一規格としてAPIチェックリストを作成しました。気をつけた点としては、 SOAPではなくREST APIを基本とする 軽量なフォーマットであるJSONフォーマット スキーマチェックや自動化を可能にするJSON Schemaを活用 があります。これらを守ることで利用企業様の困らないAPIが実現できると考えています。 ※ APIチェックリストについては以下の記事を参照してください。 適切なAPIを設計するために注意したいこと「インタフェース」 データフォーマット バージョン管理、同期・非同期 セキュリティ エンタープライズにおけるAPI提供というのは、社内システムのオープン化とも言えます。従来の業務システムというのは利用者が限定的であるため、メンテナンスを含め一時的に停止している時間があってもさほど問題にはなりませんでした。しかしAPI化すると言うことは外部からの自動化に利用されますので停止時間や情報の鮮度などが問題になります。そういった点も考慮してシステム開発されていなければなりませんので一定の枠組みを通して意識改革も行う必要があると考えています。 公開するだけではダメ。その次のステップは？ 過去10年、多くのAPIが作られてきましたが作りっぱなしで終わっているケースも多く見られます。それを防ぐために、 他社のAPIを使ったマッシュアップ例の提示 APIを使ったアプリケーション、ツール、サンプルコード などが必要だと考えています。目下、そうした開発を支援するための仕組みやライブラリを充実させていこうと考えています。 実際にAPIを使って開発をしていこうとしている開発者から度々聞かれる声としては、開発の規模感が分からないと言った意見があります。これは実際、作りたいアプリケーションの規模感によって異なりますので、まずはエンジニアが中心となってAPIを使った小さなコードを書くところからはじめて、肌感覚を鍛えて欲しいと考えています。いきなり大きなものを作ろうとするのではなく、小さくはじめて徐々に大きくしていくと言った形です。 APIゲートウェイとして目指す形は？ まずは自社サービスをAPI化していこうというのが第一段階です。その後の段階としては私たちの顧客たる企業様のサービスをAPI化し、その管理、運用を行っていこうと考えています。とはいえ、現段階ではネットワークとクラウドについてAPI化を進めている段階なので、全体としてみればまだ2、3割といったところです。 また、IoT分野にも力を入れていきます。例えばAPIゲートウェイはIoTデバイスと開発者との間に立つ、いわゆるハブになると考えています。デバイスから収集したデータ、閾値などをAPIを通して公開していきます。さらにWebHookやWebSocketなどを使って情報を相互にプッシュしていく仕組みを導入すると言った予定もあります。 2年前くらいではAPIはまだ開発者が肌感覚で知っている程度でした。その後、昨年くらいから経営層においてもAPIの重要性が認知されるようになってきました。既存のサービスにAPIを追加するのは時間がかかるのですが、新規でサービスを開発する際においてはAPIを最初から準備しておく「APIファースト」によって開発コストは1.1〜1.2倍としつつも、効果を2〜3倍とするような広め方をしたいと考えています。 とはいえエンタープライズにおけるAPI活用はまだまだです。そこで私たちとしてはNTTコミュニケーションズ関係なしに、まずエンタープライズでのAPI活用を盛り上げるべく、 Enterprise APIs Hack-Night を企画しています。定期的に開催していきますのでぜひ参加してください！

APIはシステム間連携、特に自動化に用いられることが多いため、一旦仕様が決まるとなかなか変更が難しいものです。そのためついつい触らぬ神のたたりなしとばかりにAPIの利用する側でどうにかしようと考えてしまいがちです。 しかし海外の各サービスで提供されているサービスについて見てみると、積極的なアップデートが行われているのに気付かされます。APIのアップデート情報を提供しているのが API Changelog です。 Twitterの例 例えば TwitterのAPI を見てみた場合、ほぼ毎日のレベルで修正が行われているのが分かるでしょう。ロジック側の変更だけでなく、ドキュメントの修正も行われています。ドキュメントの訂正もあるでしょうが、その多くは仕様変更に伴う修正と思われます。 どんなメリットがあるのか このような頻繁なアップデートのメリットとしてはAPIの開発がアジャイル的に、短いイテレーションの中で繰り返せるというメリットがあります。小さな変更を繰り返す形式は最近のシステム開発で取り入れられており、システム開発に伴う大きな問題である手戻りリスクを低減してくれます。 またシステムの大きな変更はそれに伴うリスク（起動しない、予期していなかったエラーが出るなど）も肥大化します。頻繁な変更とそれに伴うデプロイを行っているというのはそれだけリスクを低減できるはずです。 どんなデメリットがあるのか 最も大きいデメリットとしては仕様変更に伴う既存システムが動作しなくなることでしょう。バリデーションやパラメータの追加はこのリスクを含んでいます。この問題については自動テストを用意した上で、後方互換性を維持できるようにしなければなりません。 また、API連携の場合は無休で動き続けるケースが多いので、ゼロタイムなダウンタイムでのデプロイができるようになっている必要があるかも知れません。または予めメンテナンス状態を用意し、API利用側はそのAPIを試した上で使わなければならないといった仕組みを考えておく必要があります。 API利用者側がすべきこと ひるがえってAPI利用者側の立場で考えた場合、APIの更新情報もきちんと確認し続ける必要があるでしょう。とはいえ一年に一回あるかないか分からない更新に対して適切に対応するのも難しいのは事実です。そこで API Changelog のようなサービスを利用し、自分が使っているAPIについて更新情報を適切にフォローできるようにしておきましょう。 特に海外では突然サービスを停止してしまうことも多々あります。一度作ったら終わりではなく、定期的なステータスチェックに加えてサービス自体の継続性についても確認が必要でしょう。 APIは従来の全銀手順であったり、団体などが標準を定義している訳ではないので各企業が自由に設計、提供しています（OAuth2やRSS/Atomのように仕様が定まっているものもあります）。そのため変更もまた企業のビジネス環境の変化や時代に合わせて自由に行われます。 開発者としては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ドキュメントを適切に整備していくためにはツールの使いやすさはもちろんのこと、ベースになる記法やそのルールの分かりやすさも重要になってくるでしょう。 ぜひこれらのツールを参考に、他の開発者にとって分かりやすいドキュメントを書いてください。

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ドキュメントを適切に整備していくためにはツールの使いやすさはもちろんのこと、ベースになる記法やそのルールの分かりやすさも重要になってくるでしょう。 ぜひこれらのツールを参考に、他の開発者にとって分かりやすいドキュメントを書いてください。