7月22日に行われたAPI Meetup Tokyo #15はOpenAPI Specification（旧Swagger）特集でした。イベントの告知後、あっという間に満席になってしまったというほど、注目が高まっているOpenAPI Specification、今回はそのレポートになります。 1. OpenAPI Specification/Swagger概要 API Meetup運営チーム/Apigee 関谷和愛さん OAS（OpenAPI Specification）はREST API記述のフォーマットになります。IDLの一種で、APIを機械可読な形で記述して様々な自動処理につなぐことができます。ざっくりいうとWSDLのREST版です。 Swaggerは純粋に社内のツールとして作ったのがはじまりです。JSONだけじゃなくYAMLでも書けるようになったり、一つのファイルにまとめるといった機能が追加されていきました。Swagger 2.0がOAS 2.0に名前を変えたので、中身は同じものです。Swaggerというと、ツール群も含んだ名称になっていました。今後はOASといった場合は記述フォーマットを指します。 APIのエコシステムを作りやすい環境を作っていくのがOAI(OpenAPI Initiatize)になります。OASの目指すところはAPIライフサイクル全体をカバーするフレームワークであって、単なるドキュメント生成ツールではありません。例えば以下のような展開があります。 設計ツール ドキュメント テストケース モック バリデーション スケルトンコード SDK OAS3.0は直接の互換性は保たれない模様です。GitHub上で議論、開発しているので仕様策定に参加することも可能です。リリースは秋頃を予定しています。TDC（Technical Developer Community）がリードしています。 2. OpenAPI Specification を使ったスマートな API 運用 株式会社 KUFU 芹澤雅人さん 仕様書は大事だけど軽視されがちです。今回はそのケーススタディになります。 黎明期のWeb API 2000年代初頭に実装されたAPIです。実装言語はJava、レスポンスはXML、仕様書はWordとなっています。 欠点として、そもそも仕様書が運用されていませんでした。記載の抜け洩れが目立ち、実装を確認した方が早いといった状況です。仕様書がしっかりしていないと開発はもちろんコミュニケーションコストが大きくなってしまいました。さらに設計思想の不統一が起きやすくなっており、仕組みを作らないと開発者は仕様書をメンテナンスしない実例となりました。 2011年頃 言語はJavaで、SphinxをI/F仕様書にしました。 良かった点として、Sphinxを採用したことです。Sphinxはrstで記述する仕組みです。ソースコードで同じリポジトリで管理していたので、レビュー対象となるので抜け洩れしづらくなっていました。文書はHTML/PDFに変換できました。 欠点として、仕様書の運用コストが少なからずありました。また、エンドポイントを追加する時などは結構なコピペ作業がったり、エンタープライズ向けに別で仕様書を生成できませんでした。エンタープライズ企業向けに綺麗な仕様書を作ると喜ばれ、心なしか問い合わせも友好的でした。 ここでの学びとしては、仕様書とソースコードは近ければ近いほど良いということです。また、HTML以外のフォーマットでとれるといいと思います。 最近のWeb API 最近はSmartHR APIで実践しています。言語はRubyを使っています。先にWeb APIを実装して、後からSwagger Specを生成するアプローチとなっています。デザインも良いですし、運用コストも気にならないレベルまできています。 3. Swaggerを使用したモデルファーストなAPI開発のよもやま話 TIS株式会社 小西啓介さん スマホアプリ向けのAPI開発でAPI仕様をExcelで書きたくありませんでした。漏れのないフォーマットが作れませんし、APIスタブを生成したくてSwaggerにたどり着きました。 とは言え、最初はExcelなどで整理するところからはじめました。 業務機能の洗い出し リソース抽出 項目名の名寄せ、英字検討 Swaggerは項目名だけを書くようにしています。 Path Operation 必須リクエストパラメータ いきなり細かく書くのではなく、骨格が固まったら詳細記述するようにしています。 Swagger Editorについて とても使いやすいわけではありません。構文エラーを取るのは一苦労です。他のツールで作成してから貼り付けると多数のエラーが出ます。気付きづらい機能として、Ctrl + Fを2回で置換が出ます。なお、Swagger UIとの互換性はありません。 Swagger UIについて カスタマイズが必要です。例えば認証関係、バグパッチ対応、日本語化など。なお、表示されるレスポンスは加工されています。例えば、 CORSのXHRでのエラーは不明 304は200で表示 などです。また、表示されないSwaggerの情報があります。そのためSwaggerファイルも公開すべきです。後、アルファベット順で必ずソートされるのが仕様となっています。 Swagger Nodeについて フォーマットバリデーションが便利です。リクエストだけでなくレスポンスのバリデーションもしてくれます。なお、additionalProperties:falseにすると大変です。 Swagger仕様について 全体の構成が分かりづらいです。例えばリクエストとレスポンスが非対称で、リクエストは配列、レスポンスはマップで定義という違いがあります。 OpenAPI Specification Visual Documantationというサイトが便利そうでした。大事な部分はJSON Schema参照しましょう。両方見ないと分からないことがあります。 hostパラメータは任意 セキュリティ定義の（authorization uri/token uri）は絶対URLでhostとは無関係 external doucmentを使えるが、表示されない 内部用、外部用に別に分けたいが一つのファイルの方が良いです。それを表示する際にフィルタリングするようにしましょう。 よく使うDefinitionの参照先は2つあります。 Request Definition Response Definition Definition descriptionの中にはGitHub Flavoredが使えるものと使えないものがあるので注意してください。 4. Lightning Talks by Open API Initiative members! ここではLTとしてOpenAPI Initiatizeに参画している企業からその取り組みについて紹介がありました。 Mashape Augusto Mariettiさん Mashapeは開発ツールを提供しています。API管理用ツールを提供しています。 マーケットプレイス APIゲートウェイ（Kong）、オープンソース Gelato - Developer Portal キーの管理もできる アクセス管理 Swaggerサポート Galileo API解析 APIトラフィック Paypal 岡村純一さん PayPalはなぜ参加しているのか？それは二つあって、 対外的要因：より多くの人に使ってもらうため 対内的要因：製品を効率よく開発するため PayPalのAPIが他のAPIと共通化されていれば使ってもらいやすくなるでしょう。内部APIも共通化されると内部でも開発しやすくなるんじゃないかと考えています。 PayPalは単なる決済APIからペイメントOSへと発展しています。社内の開発体制が大きくなっていくと、様々な言語で作られるようになります。一貫性を保つ、コミュニケーションコストの増大を防ぐのに共通フォーマットが必要になると考えています。 IBM 森住祐介さん IBM API Connectについて紹介します。StrongLoopを買収したことでAPIの作成、実行、管理、保護までできるようになりました。 どうやって迅速に開発するのか APIを実行するランタイムの品質と性能を確保するには？ 管理を効率的に行うには？ APIをセキュリティに運営するには？ クラウド、オンプレミスで柔軟に利用可能です。開発時、ローカルも使えます。 CLIでOAIに則った仕様書を作成できたり、GUIも提供されています。 Microsoft 佐藤直樹さん Visual Studioプロジェクトテンプレートではアクセス制約、セキュリティを意識する場合はAPIゲートウェイが使えます。SwaggerからのAPIインポートがサポートされています。API AppsとLogic AppもSwaggerで連携できます。 Swashbuckle がSwagger API定義が生成します。Visual Studioにデフォルトで入っており、オープンソース・ソフトウェアです。API定義、CORS設定がLogic Appsとの連携を担います。Swaggerの直接読み込みやAPI Appsとの連携が行えます。 なお、Microsoftでは自社でも積極的に自社製品を使っています。 Microsoft REST API Guideline が最近リリースされました。ぜひご覧ください！ Apigee 関谷和愛さん ApigeeはAPI管理サービスを提供しています。Swagger EditorはApigeeのコントリビューションですが、Swagger UIは別な会社です。この辺りが連携での齟齬につながっているのだと思います。 OASについては次のようなサービスでサポートしています。 APIゲートウェイ / Apigee Proxy 利用者ポータル / Apigee Edge API開発環境 / Apigee API Studio テスト・監視 / Apigee Test OpenAPI Specificationは今後のAPI開発において無視できない仕様となっていくでしょう。今回の勉強会では余すところなく、それらの情報がキャッチアップできていたと思われます。

開発したAPIを広めるために行っていきたい施策を紹介します。ただ漫然と公開すれば良いのではなく、より広めていくための活動を行ってこそ、APIを使ったビジネス化が実現できるようになるでしょう。 自分たちが率先して使う 開発したAPIを外部企業に使って欲しいと待っているだけではダメです。そのAPIを自ら使って新しいビジネスの可能性を見せなければなりません。少なくとも基幹システムの中で使ったり、サーバサイドのレンダリングだった部分をAPIベースに置き換えると言った利用が考えられます。 自ら使うことでAPIの問題点を知ったり、改善に繋げられるようになります。使い方によっては未知のエラーが発生したり、機能の過不足に気付かされることでしょう。 事例を作る 逆説的ではあるのですが、率先してリスクをとって挑戦していく企業は希です。多くは先鞭をつけた事例を見て、自社への適用法を考えることでしょう。そのため、事例がなければ誰もが躊躇してしまうはずです。 自社自ら事例を作ることもできますし、パートナーへ依頼して事例を作ってもらうこともできます。なお、その際には事例として掲載することを予め承諾を得ておくと言ったことや、事例化することによるメリット（メディアへのパブリッシングなど）を明確にしておく必要があります。多くの場合、APIを利用したという事例化によるクライアント側企業のメリットは多くありません。 頻繁な更新と機能追加 更新が途絶えたAPIは誰も使いたいと思わないでしょう。APIという特性上、あまり更新が頻繁なのも考え物ですが、それでもトレンドに合わせた機能追加やパフォーマンス向上をしていくべきです。 互換性の維持と機能追加は矛盾することもありますが、バージョン管理を意識した運用も考えるべきです。 ドキュメントの充実 APIの利用法は、内部の人にすれば常識的であったり、察するレベルだったりするかも知れません。しかし外部の開発者にとっては全くの未知なるもので、簡単なドキュメントを読んだだけですべてを理解するのは不可能です。 ドキュメントは徹底して充実させなければなりません。APIはシステム向けのものなのでついSwaggerなどで自動生成したものだけになりがちですが、他にもチュートリアルやサンプルなど、提供すべきドキュメントはたくさん考えられます。 使えるサンプルコードの提供 一言でサンプルコードと言っても多くのパターンが考えられます。まずHello World級の簡単なものが考えられます。これは基本です。次により実践的なコードが考えられますが、これが大きな問題になるでしょう。 あまり複雑なものは開発者が理解するだけでも大変であったり、本質的ではないコードも増えてしまいます。かといって提供側の視点だけでサンプルを書くと、あまり使い物にならないコードができてしまうでしょう。これは利用者の意見を聞きつつ、使えるコードは何かを考えていく必要があります。 利用開始までの敷居を極力下げる 多くの利用者が増えないAPIは利用開始までのステップがとても多いことが問題です。Slackはチャット連携アプリケーションが爆発的に増えましたが、その大きな要因となったのは利用までの手軽さだったと言えます。 複雑な仕組みが必要な場合は専用ライブラリであったり、SDKの提供が欠かせません。ただしその場合はソフトウェアの使い方を覚えたり、そもそもの開発コストがかかってしまうのが難点と言えます。 なるべくシンプルに、すぐに使い方を覚えられて使いこなせる、そんなAPIを開発すべきでしょう。 APIによるビジネス変化は待っていければ起きるものではなく、自分たちから率先してアクションを起こしていかなければなりません。開発が必要である以上、よほどのメリットがなければ利用しようと考えないはずです。 相手にとっての利便性を第一に考えた上で、APIの仕組みや利用までの手順、サポートなどを充実させていきましょう。

APIにはHTTPアクセスをそのまま提供するだけのものもありますが、SDKや専用ライブラリを提供しているものもあります。今回はそんなSDK、ライブラリを利用する（または提供する）メリット、デメリットを挙げたいと思います。 メリット 利用者側の視点で考えた場合、次のようなメリットが考えられます。 HTTPアクセス部分を意識しないで済む APIにおけるHTTPリクエストの作成を意識しないで済むようになるのがSDK/ライブラリのメリットです。特にOAuth2リクエストのように署名を生成するような部分は実装が面倒、かつ検証も大変なのでメリットがあります。 これは提供側にとってもメリットがあります。自作ライブラリでのアクセスは当然エラーが頻発します。また、予想外のアクセス方法をしてくるかも知れません。SDKであれば、自分たちが開発している範疇でのアクセスに限定されますので、パフォーマンスを向上させる計画も立てやすくなります。 APIのバージョンアップを気にしない APIをバージョンアップした際には項目が追加または削除されたり、構造が変わったりする可能性があります。HTTPアクセスを通して使っている場合、こういった変化がシステムエラーにつながるためにバージョンアップを躊躇してしまいがちです。 SDKを使っている場合、そうした差分はSDKで吸収できます。SDK側で過去のバージョンに合わせたレスポンスに加工しておくことで、不用意なエラー発生を防ぐことができます。 デメリット SDK/ライブラリの提供によるデメリットは多数あります。このため、開発者によっては導入を控えてしまうと言うのはよくある話です。 SDK、ライブラリのバグ SDK、ライブラリがバグを含んでいたりすると、開発者にはとても嫌われる要因になります。開発者は自分の開発した範囲については責任を持ちますが、それが他者の開発したコードに起因するものだとするととてもストレスを感じるものです。 特にスマートフォンアプリの場合、修正と審査によって時間がかかるため、修正が即座に反映されません。そのため、SDKがバグを多く含んでいる場合、開発者はサービス自体の利用を止めてしまう可能性があります。 提供側としてはバグを含めないようにするのはもちろんのこと、省メモリであったり、サイズを小さくする、オープンソースにすることで開発者自身が原因を調べたり改善できる可能性を残すと言った回避策が考えられます。 特にSDKの場合、ネットワークがオフラインである場合を考慮して開発する必要があります。APIはネットワークがなければ意味がありませんが、オフライン時にメソッドをコールしても正しく動作し続けなければなりません。 動作が重たくなる可能性 SDKのサイズが大きかったり、余計なことをしているために動作が重たくなることがあります。開発者としては自分の作成したシステムやアプリが重たくなるのは嫌います。それがSDKのようにブラックボックス的に使っている部分だと特にです。 もちろん、SDKによって動作が軽くなると言うのは難しいですが、全体のコード量を減らせる可能性はあります。提供側としてはそういった視点で開発する必要があるでしょう。 更新が面倒 SDK/ライブラリが頻繁にアップデートを繰り返す場合、開発者はアップデートが面倒に感じてしまうものです。せめてパッケージ管理システムを利用するなどアップデートの手間を減らすべきです。 また、SDK/ライブラリレベルでのインタフェースは統一しておかなければなりません。インタフェースが変わってしまうとコードの修正が必要になりますので開発者にとって大きな負担となります。そのため引数も直接指定するのではなく、ハッシュを使って柔軟に設定できるようにしておくなどの工夫が必要です。 他のライブラリとのコンフリクト SDK/ライブラリによってはさらに外部ライブラリを使っているケースがあります。また、Webサービスやスマートフォンアプリは他にもたくさんのライブラリを導入しているでしょう。そうした外部ライブラリとコンフリクトを起こすのは危険です。開発者は取捨選択しなければならないからです。 時に、ライブラリの読み込み順番によってエラーが出たり出なかったりするケースがありますが、これは開発者にとって大きなストレスになります。SDKの信頼性にもつながるでしょう。 提供側としては自分たちのコードだけでなく、外部ライブラリとの組み合わせによるテストも行わなければならないでしょう。 SDKインタフェース SDKやライブラリはただ動けば良いという訳ではなく、そのインタフェースや設計思想が開発者に与える印象は大きいです。SDKはモダンな開発手法を使い、インタフェースもモダンである必要があります。 モダンな開発手法もトレンドがあります。パッケージ管理も状況が変わります。そうした開発トレンドに合わせてバージョンアップしていく必要があるでしょう。 開発コスト 提供側にとって大きな問題は開発コストです。プログラミング言語は多数あり、どれに対してライブラリを提供するかが問題です。一度の提供は簡単ですが、バグフィックスであったり、APIの更新に合わせた修正は大きなコストにつながるのでライブラリのプログラミング言語の選定は注意が必要です。 APIの利用を広める上でSDK/ライブラリの提供は大きな意味を持ちます。しかしその品質によっては開発者の信頼を大きく損なったり、API自体の採用を控えてしまうことになりかねません。提供側としてSDK/ライブラリを提供する場合は慎重な設計と品質、パフォーマンスに十分気を配る必要があるでしょう。

APIを多用して開発を進めていると、次第にシステムが複雑になってくるのが実感できるはずです。要因を挙げつつ、その回避策を紹介します。 APIの種類の増加 データを検索、加工、保存、外部への通知など様々なデータソースに対してAPIリクエストを行っていると、その管理が煩雑になってきます。最も大きなリスクとしては、一社のサービスが停止した場合に処理全体が止まる可能性があることでしょう。また、契約も複数企業と行うことになり、サービスレベルの統一も難しくなります。 回避策として、多くの企業ではなく一社にまとめてしまうという方法があります。特定企業だけが提供する機能である場合は難しいですが、クラウドサーバのような汎用的な機能であれば選定先は数多く存在するでしょう。そうしてAPI提供企業を絞り込むことで、サービスレベルの統一が可能になります。依存リスクは高まりますが、元々使っているAPIがあるのであれば一定のリスクは存在するでしょう。 ネットワーク接続先の増加 APIは一般的にHTTP/HTTPS接続によって提供されるので、実行するAPIが増えればその分、ネットワークの接続先が増えていきます。ユーザからのリクエスト、サーバからAPIのコールとその結果待ち、そしてユーザへのレスポンスと複数のネットワークコールが行われると、その分レスポンスが遅くなってしまいます。 回避先として、JavaScriptベースのAPIがあればユーザブラウザから直接コールしてもらうという方法があります。そして、ユーザが受け取った結果を自社サーバに転送してもらうのです。 ネットワーク遅延に伴う実行速度低下 APIで最も問題になるのがネットワークの遅延です。特に複数回APIをコールしなければならない状態において、一つのAPIコールの結果を待って処理しなければならない場合は大きな問題になります。 こうした問題はAPI同士が密結合することによって起こります。しかしAPI自体はなるべく疎結合になっているべきで、システムの設計上問題があるかも知れません。また、ネットワークアクセスはnode.jsのように非同期実行できる言語を採用したり、バックグラウンド処理に回すことでユーザレスポンスを改善できる可能性があります。 サービス終了に伴うリスクの増加 APIを使う上での最大のリスクと言えます。これを回避するのは契約上の縛りと、代替サービスを平行して使う方法があります。 ビジネスで使うAPIであれば、SLAの保証は適切に行われなければなりません。その意味において、無料で提供されるAPIほど怖いものはないでしょう。無料だからと気軽に使っていると、API提供側もビジネスとして成り立たず、突然終了する可能性があります。 代替サービスを常に探しておくのも大事です。世の中には数万のAPIが存在しており、類似APIは多数存在します。ただしインタフェースが異なるケースは多いので、APIコール部分をラッピングし、代替サービスへの乗り換えを容易に行えるようにあらかじめ準備しておくのが良いでしょう。 一旦複雑化したシステムをリファクタリングするのはそうそう簡単なことではありません。あらかじめそうしたリスクを勘案し、設計やコーディングに反映しておくのが大事です。

今回は、メール配信やメールマガジンサービスにおいてAPIが提供されているサービスをまとめました。メールマーケティングは今なお根強く使われている手法で、API連携によってマーケティングオートメーション、ワントゥワンマーケティングが実現できます。 WEBCAS WEBCASは、毎時300万通にも及ぶ大量高速メール配信が可能なメール配信システムです。既存システムに連携するためのAPIも用意しているため、想定のシステム構成に合わせて自由に設計が可能です。 WEBCASのAPIではバッチ処理がサポートされており、顧客リストを自動で取得し、任意のタイミングでWEBCAS管理画面からメール配信できます。その結果、業務処理の効率化が実現できます。 配信データ連携として、メール配信リストの取り込みや、CSVデータ形式でもアドレスを一括登録できるようです。その他、メール配信だけではなく、メールマーケティングにも利用できる機能があり、非常によく考えられたシステムです。 クルメル クルメルは、自社システム等の顧客情報などからAPI連携を行います。機能としては、顧客リストのアップロード、メール情報や配信エラーなどAPI連携を中心に基本機能を抑え、マーケティングに必要な情報も取得できるので、既存CRMとの連携も設計しやすそうです。 ※ 無料トライアルもあるようです。 Cuenote FC 会員データーベースと連携してメールを送ることはもちろん、レコメンド機能やDMPなど外部連携も可能となっています。 メール配信としては配信リスト登録、メール文書登録、配信予約などとなっており、これらの機能は外部システムから制御可能です。 既存の会員データベースをCSVインポート機能を利用して連携できるので、初期の導入には手間が掛からないのではないでしょうか。 ※ 試用版があるようです。 スリーメール 既存システムや独自データベースとの連携が可能で、通信はXMLで行います。他にも、基本的な配信機能に加えて添付ファウルウィルスチェックなどセキュリティも充実しており、最大で時間当たり100万通の高速配信を実現します。 クライゼル クライゼルのメール配信APIは、CRMシステムがベースとなっていて、メールマーケティングを組み合わせて利用することで威力を発揮します。 他にもCRM機能へのAPIもありますが、メールAPIとしては、会員登録、メールアップロード、配信予約と基本的な機能がそろいます。 コンビーズメールプラス 既存のシステム構成にコンビーズからもAPI連携を行うことで、メール送信等を行うシステムです。そのため、既存のシステムに合わせて自由に設計できるAPIとなっているのですが、逆にカスタマイズする必要もあるでしょう。 また、APIはβ版とあるので、開発時には注意が必要です。機能的には読者登録はもちろん、予約配信、配信状況、配信グループの設定などの機能があり、メールAPIとしての基本的な機能がそろっています。 開封率の確認などもできるので、メールマーケティングにおいても有用でしょう。 auto-mail auto-mailは、メール配信を外部システムから簡単に連携できるシステムです。XMLでの配信を行い、必要な情報もそこに含めて送信するのでAPI通信といっても特に複雑な開発は必要ないようです。 また、メールアドレスの個人情報なども90日で自動削除してくれる機能がついてます。最近では情報セキュリティで問題になる事も多くなっていますので、この機能はメール管理者としては嬉しいのではないでしょうか？ いかがでしょうか。各サービスともに基本機能はほぼカバーしており、後は既存システムとの設計の柔軟性、価格と機能の割り切りかたで、ほぼ絞られるかと思います。 自社システムはもちろんですが、企業戦略上の相性が問われるでしょう。ぜひ本記事を参考にしてください。

APIを設計する上でバージョン管理をどのように行うかは常に頭を悩ませる問題です。しかし、そもそもバージョン管理が必要なのでしょうか。今回はそんな問題提起と、その解決策の紹介です。 結局バージョン2が出てこない APIのあるある問題として、バージョン管理を盛り込んだのはいいけれど、結局新しいバージョンが出てこないという問題があります。いつまでも/v1/のまま運用していないでしょうか。ムダにURLを長くしてしまっているだけの可能性があります。 ポリシーが不明確 v1のまま運用しているからといって、APIが全く更新されていないかといえばそうではありません。多くのサービスはきちんと運営されており、APIもそれに合わせて更新されています。しかしv1に機能追加という形で行われている場合がほとんどです。 問題はどういった場合にv2にするかというポリシーが不明確であるということです。バージョンを上げる理由をきちんと作らなければならないのですが、あまり頻繁にあげると開発者を混乱させる可能性があったり、過去バージョンのレスポンスをサポートし続けなければならないといった運用上の問題も出てきます。 一部だけ更新はありえない さらに一部の機能だけ v2 になるということはありません。開発者としてもある機能を呼ぶときだけ v2 を、それ以外は v1 を呼ぶというのは非常に面倒になります。そこで基本的に全機能が v2 となっても利用でき、一部の機能だけ v2 として提供されるのが一般的です。つまり古い機能についてはエイリアスになります。 その場合、ドキュメント整備の問題があったり、実際には v1 と v2 の機能が同じなど開発者を混乱させてしまう可能性があります。 解決策 APIのバージョン管理については幾つかの方法がありますが、多くの場合開発者や、その開発者が使っているアプリごとに使いたいバージョンは決まっているという事実があります。そこで、利用するAPIのバージョンを設定画面を使って指定してもらうという方法が考えられます。 そうすることで、URL上からはバージョン番号を消すことができます。常に同じURLにアクセスするので利便性が高まるでしょう。また、運営側としてもどのバージョンのAPIが使われているかを管理しやすくなり、過去バージョンのAPIに対する保守管理を行うかどうか判断しやすくなります。 または思いきってバージョン管理を考えないという方法も考えられます。おそらく殆どの場合において、バージョン管理は利用されません。であれば、常に同じエンドポイントをメンテナンスし続ける方が安心ではないでしょうか。バージョン番号による余計な分岐処理はコードを見づらくしたり、後方互換性における開発コスト増につながります。そういった余計なコストをなくせるようになるでしょう。 適切なAPIのバージョン管理は適切なポシリーがあってこそ成り立つものです。もしバージョン管理を設計に含めるのであれば、まずポシリーの設定が求められるでしょう。

クラウド化の進歩によってビッグデータが扱えるようになり、更に脚光を浴びている機械学習。実は事の発端は意外に古く、1950年代には研究が始まっていたとされています。今回は、機械学習のAPIについてまとめてみました。 Prediction API Googleの機械学習サービス Prediction API です。トレーニングデータの学習など、RESTful APIをサポートしており、Cloud Platform の各サービスとシームレスに連携が可能です。 それはGoogleスプレッドシートにも及び、直接スプレッドシート内でPrediction APIが利用できます。これは、他にはないアドバンテージではないでしょうか。具体的にはSmartAutoFillというプラグインをAdd-onするのですが、 使ってみたところ、セルを選択するだけという手軽さで予測値が取得できます。 Smart Autofill Spreadsheets Add On ドキュメント類は殆どが英語となっていますが、非常に見やすい内容となっております。まだオープンソース化して間もないですが（2015年11月にオープンソース化）情報などはこれからどんどん増えていくことでしょう。 料金体系などは、無償と有償の2つとなっていて、無償枠では確認で試すのに十分な数値となっているようです。詳しくは、以下の料金体系を参照して下さい。 SLAについては 有償サービスで99.9% の稼働率となっています。詳しい 料金体系はこちら です。 ドキュメント クイックスタート Microsoft Azure Machine Learning MicrosoftのAzureサービスにおける、機械学習サービスです。主に、Machine Learning Studioのグラフィカルインターフェースが素晴らしいのですが、GUIでの操作の他にもAPIでの操作も可能となっています。 無料枠での利用では、ステージングでの運用のみ可能となっており、実稼働環境に移行した際にエンドポイントを取得するには、スタンダードプラン（後述）以上が必要のようです。 ドキュメントはほぼ日本語での資料がそろっており、チュートリアルもグラフィカルインターフェースの管理画面が解りやすく説明されています。書籍も販売されており、学習コストは低いと考えてよいでしょう。 料金体系はAzureとは別となっており、Freeプラン、スタンダードプランの2種類となります。スタンダードプランでは、完全な従量課金制で1000〜2000円程から利用できます。詳細な価格については 価格の詳細ページ を見てください。 SLAにおいては「マイクロソフトは、Request Response Service (RRS) に関して API トランザクションの 99.95% の可用性を保証します。」とあります。 ドキュメント チュートリアル Amazon Machine Learning| AWS AWSでの分析系サービスの一つ、Amazon Machine Learningです。 ドキュメント類は英語ですが、非常に内容が充実しています。ちょっと解りにくいのが、どこにサービス自体があるのかが、サービスが多くわかりにくいかも知れません。 コンソールにログイン後、分析のエリアにありますので探してみて下さい。また、リージョンは執筆時点ではアメリカ東部とEU（アイルランド）のみとなっています。 具体的な操作については、チュートリアルを一通り行えば、大体解るでしょう。 料金などAWSは非常に解りにくいのですが、データ分析およびモデル構築料金は他のサービスと比べ、0.42 USD/時と割合高めに設定されているようです。詳しくは データ分析およびモデル構築料金 を参照下さい。 12ヶ月のAWS無料利用枠で、AWSAmazon Machine Learning サービスは現在利用できないようです。注意文言をスルーしてしまいそうになりました。利用時には注意して下さい。 ドキュメント チュートリアル bigml bigmlは、クラウドで機械学習の予測分析ができるAPIサービスです。画面はグラフィカルで使いやすく、小難しい機械学習という感じはしません。ログインすると、すぐに使い始めることができます。 サンプルデータもいくつか用意されていますので、一通りさわってみることで、大まかな感じは掴めると思います。 Webサービスでは、RESTFullによるAPIも用意されており、全ての制御が可能となっています。ドキュメントもしっかりしていますので、利用に迷うことはあまりないでしょう。 ドキュメントはこちら です。 料金は、月額プランが30ドルからで、年間プランで一括請求であれば、年240ドル（月額換算で20ドル）からとなっています。ただし、利用サイズやデータ量にもよるので注意が必要です。 indico ログインするとAPI Keyが発行されますので、それを利用してすぐにコーディングが始められます。Python、Ruby、Java、NodeJS、PHP、Rのサンプルもついていますので、 プログラミングに慣れていれば、すぐに理解できるでしょう。 以下のデモは、テキストのSentiment度合いのサンプルです。実際のコーディング例もついているので参考になると思います。 APIは、1万コール/月まで無料となっており、それ以降は、有料となりますが比較的低料金です。また、現時点では対応言語が英語となっていますが、手始めに取りかかるには、非常に簡単に始めることのできる機械学習サービスAPIだと思います。 機械学習というと、なにやら難しく構えてしまいそうです。しかし、実際に手を動かしてみると当初思ったほどではなく、回帰分析やベイジアンフィルターなど、そのようなことは深く考えなくてもあっさりと動いてしまうという印象を受けました（とはいえ知っていた方が間違いないです）。 企業における情報処理では、ビッグデータを活用して データのフィルタリング、商品レコメンドなどが当たり前のように導入されており、それが身近に感じられるようになってきています。殆どのサービスで無料枠があるので、ぜひこの機会にいじり倒してみてください。

6月23日（木）にEnterprise APIs Hack-Night #5が開催されました。前回からxTechを全体のテーマとしており、今回はRetailTech × APIとなっています。こちらの記事は各登壇者の内容レポートです。 モノのハブステーション「minikura API」 登壇者：寺田倉庫 システムグループ藏森安治さん モノのハブステーション minikura API from minikura 寺田倉庫は1950年創業の企業で、Webサービスは5年前、Web APIは2年前から出しています。 minikuraを簡単に説明すると、Webで申し込みできるトランクルームになります。通常のトランクルームは契約はもちろん、利用も面倒です。さらに借りた後も車に積めたり、鍵を開けたりするのが面倒でした。mikuraはWebで申し込みもできて、荷物を送るのも簡単にできます。送られてきた物は検品し、一点一点データベース登録します。 そして、minikura APIはminikuraの全機能が使えます。ものを入れる、入れたものを見る、入っているものを出すの3種類の機能がベースとなっています。開発はまずAPIから行うようになっており、現時点で150本を超えるAPIを提供しています。バイマのリセール、エアークローゼット、サマリーのサマリーポケットなどといったサービスのバックヤードも提供しています。 minikura APIのここだけの話 エンタープライズ企業におけるAPI化の方法 API提供によって、語るべき人に語ってもらえるようになりました。私たちは消費者と距離がありますが、各サービス事業者がサービス利用者に分かりやすい形でサービスを紹介してもらえています。その結果、これまでにない商品を預かるようにもなっています。 私たちはすでに確立したワークフローがあり、それを変更するのはとても大変でした。そこでまず会員登録だけAPI化し、徐々に広げていったのが今の形です。エンタープライズ企業におけるAPI化を担うのは開発者であると言え、その意味では開発者は失敗を恐れずやっていって欲しいと思っています。 サンドボックスが大事 minikura APIを叩くと倉庫や人が動くことになります。ちょっとした試用が業務に混乱をもたらしかねません。その意味ではサンドボックス環境がとても大事で、B2Bにおいては特にサンドボックス環境がないとトラブルになりかねません。 寝た子は起こすな 私たちは「預かるにイノベーションを」起こしたいと考えています。そんな中、私たちの業界では「寝た子は起こすな」という言葉があります。倉庫に置きっ放しになっている（塩漬け状態）になっている顧客に案内メールを出して出庫されたらたまらない、という訳です。 しかしイノベーションを起こすためには預けた上で、さらに変化をもたらしたいのです。例えば次のような妄想を考えてみました。預けた後に、倉庫内で物々交換するマーケットです。倉庫内移動なのでお互いの名前も住所も知る必要がありません。さらにわらしべ長者よろしく、交換している内に自分にとって不要だったものがとても役立つものに変わるかも知れません。 私たちはそんな形で外部からのエネルギーを取り込んで新規事業を開拓しています。本社の倉庫はまだまだICT化が進んでいません。もっとBizDevを加速していきます。 Q&A 競合他社の動き（API化について）はありますか？ minikuraについては競合がいません。競合は実家と言っています。 API化によって誤発注などに対する対策は？ 大量発注はあります。API側の開発はどんどん進んでいくのですが、現場（倉庫）はまだまだICT化が進んでいないのでそのギャップが大きいと感じています。 当日の動画 物流のクラウド化 登壇者：エアークローゼット　CTO　辻亮佑さん エアークローゼットは感動するファッションの出会いを生み出したいというコンセプトのサービスです。コーディネーターが組み合わせた洋服を期限なく借りられます。そのまま購入もできますし、返却も可能です。その際、クリーニングはいりません。 サービスを作るにあたってやらなければならないことが多数ありました。 洋服の入庫およびササゲ（採寸、撮影、原稿） 1品1品を単品管理 選ばれた服をユーザに配送 こだわりの検品、クリーニング これらをすべてまるっと依頼できるのが寺田倉庫さんでした。minikuraなくしてエアークローゼットは存在しなかったとさえ言えます。洋服というリアルのものが絡む分、インターネットだけでは解決しませんし、かといってスタートアップだけでは人も足りません。 そこでminikuraの撮影付きお預かりサービスがありました。在庫の単品管理も可能で、クリーニングもできます。倉庫から指定した住所への発送も可能です。システム連携するAPIも用意されており、出会ったときには感動すら覚えました。 具体的な活用事例について紹介します。 アイテム情報連携 アイテムの指定の日付からの差分情報が取得できます。 新規入庫アイテムの取得 どのアイテムが今どこにあるのか取得 メタ情報の連携 などの情報が取得できます。 配送伝票番号取得API 配送依頼をかけたアイテムごとに、ヤマトの配送伝票番号を取得できます。レンタル出庫したユーザへ届くアイテムの配送伝票番号を送付しています。ユーザは自分でコンビニ受け取りに変更したりできます。 レンタル出庫依頼 指定したアイテムを指定したユーザへ送付します。現物確認用にオフィスへ送付するのにも使います。 アイテム情報更新 ユーザのフィードバックをもとにアイテム情報を更新します。 総括 今は実現したいことを元に、寺田倉庫さんと相互連携しながら業務オペレーションやシステムも継続的に改善しています。例えば検品APIは元々ありませんでしたが、一緒に考えて作っていきました。minikuraのサービスを使うことで、物流面の運用はすべて任せられるのでとても役立っています。 Q&A 社内DBは何を管理していますか？ フィードバックやスタイリストに関係するデータは社内DBで管理しています。 もしもminikuraがなかったら？ このサービスはなかったでしょう。企画段階から色々な倉庫にあたっている中でminikuraに出会いました。 競合の出現については？ ファッションレンタルで言うとすでにライバルは出てきていますが、コンセプトが違うので大丈夫と考えています。 エアークローゼットとminikuraの間で情報整合性については？ 過去に何度か起こったことがあります。違うアイテムと入れ替わっていたなど。その度にフローを変えて、防止策に取り組んできました。 出庫取消は？ あります。基本的に出庫取消は電話です。また、作業量の増減もあるので、デイリーで共有しています。APIにない機能は企業間コミュニケーションで解決している。 シーズンによってスケールは？ シーズンはトレンドに影響しても出庫量についてはあまり変わらない印象です。シーズンによって冬服は奥に移動するなど、オペレーション上の工夫はしています。 リクエストした機能はありますか？ たくさんあります。例えば返送用伝票に倉庫管理番号が入っているのですが、返送用伝票がなくなるとワークフローが混乱しました。しかし、元々APIがありませんでしたので、追加してもらっています。 当日の動画 iPadクラウドPOSレジにおけるAPI活用事例 登壇者：株式会社ユビレジ 取締役 竹内歩夢さん iPadクラウドPOSレジにおけるAPI活用事例 from Pomu Takeuchi ユビレジは2010年からはじまったiPad POSアプリの元祖です。約2万店舗に使ってもらっています。基本的なPOS操作はiPad、解析系はWebブラウザで使います。アルバイトでも学習コスト少なく使えるのがポイントです。 技術面の話 ユビレジでは3種類のAPIを提供しています。 Web(HTTP)API いわゆるREST APIです。差分を取得するのに特化したエンドポイントを用意しています。商品登録や会計の取得などもできます。ユビレジ自体このAPIで実現しています。 iOS URL Scheme API iOSのアプリ間連携を実現している。ユビレジから他のアプリ（決済系など）を呼び出して戻ってくる使われ方です。iOS9から条件が厳しくなってSchemeの事前の登録が必要になっています。 iOS HTTP API iPadアプリ内にHTTPサーバが立っていて、APIを提供しています。LAN内で使われています。iOS 10で制限がかかるかも知れません。 認証方法 API Token アカウントごとにAPI認証用のTokenを幾つでも発行できます。実装が簡単で、自社システム向きです。 OAuth2 サービス提供者向けです。認証、認可のフローを自動的に行えます。APIアクセス許可、拒否をエンドユーザの負担なく行えるのが利点です。アクセストークンは1日、リフレッシュトークンも2週間程度となっていて、頻繁にアクセスしないと無効になるようにしています。 ユビレジAPIは元々私が自分で経営していた会社で最初に使ったと思います。その後、ラクーン、Salesforce、トレタ、PayPal、GMO、freeeなどでも使われています。開発者向けのサンドボックスも用意しています。 APIと関連業務について オーダー管理 オーダーアプリで取った注文をiPadアプリへ受け渡してお会計します。同一端末ならURL Schemeで、別端末ならiOS HTTP APIで行います。 決済 食べログPay、楽天Pay、PayPal Here（現在終了）などの決済アプリとの連携します。それぞれの決済アプリが持っているAPIを叩く仕組みです。 生産・仕入・在庫管理 在庫管理や棚卸しを実現します。ラクーンのスーパーデリバリーで使われています。ユビレジの商品マスタをAPIで更新する仕組みです。賞味期限の早い商品は午前中の売れ行きを見て、午後の生産調整を行うといった使い方もされています。 販売管理・顧客管理 顧客情報の登録をAPIでできます。レセコン連携、売り掛けの管理、DM発送もできるようになっています。 会計 支払い方法別の金額取得がAPIで可能です。クラウドの会計サービスと連動するのに売り上げ情報を渡しています。大型で古いERPに対してmac miniを経由してデータ連係しているケースもあります。 Q&A 導入店舗はどういった業種が多いですか？ハードルはどうですか？ 飲食店がメインです（7割）。残り2割が雑貨、アパレル。残り1割が美容院、整骨院など。新規店舗だと初回の導入コストに比べると低いので問題になりまん。チェーン店はすでに設備があるので難しいことが多いです。故障など、タイミングが必要です。 アプリによってはAndroidのものもあるが、他のOSとの連携は？ データの連係だけすれば良いのでHTTP連携も使えます。 店舗側での商品/在庫管理する上で商品IDの管理は？ バーコードをキーにユビレジにも登録しているのだと思います。 企業連携する際、どれくらい期間がかかっているのか？新しく開発しているケースはあるのか？ アプリ間の決済連携は簡単で2ヶ月くらいです。会計系はテストの工程が必要で、半年くらいかかってしまいます。新機能については話を何回か聞いています。お互いのメリットを見て判断しています。 SquareやPayPalなどもPOSを提供したりしていますがいかがでしょうか。今後決済についても提供する可能性があるでしょうか？ Squareは決済ありきでPOSはおまけ。PayPal Hereも。ユビレジはPOSありき、決済は逆におまけとしています。私たちはお互いいいとこ取りして一つの大きな仕組みとしています。 当日の動画 今回は懇親会が別会場でしたが大いに盛り上がっていました。次回は8月25日にEdTechを予定しています。ぜひご参加ください！

地方自治体や政府のオープンデータでの成功事例が多くなってきました。IoTやWebサービス、事業戦略などにも利用できる可能性をを秘めた情報もあることでしょう。そんなオープンデータを探すきっかけとなるサイトをまとめました。 DATA GO JP（データカタログサイト） 政府が運用する、情報ポータルサイトです。内閣官房情報通信技術（IT）総合戦略室で企画され、総務省行政管理局が運用しているとのことです。サイト内はオープンデータの検索が出来るようになっていて、各省庁、グループ、タグ、フォーマットで絞り込めます。また、開発者向けに、サイトで利用しているデータベースそのものの「オープンデータAPI」が用意されています。機会があれば、APIを試してみてはいかでしょうか。 LinkData.org オープンデータを活用するために、データセットをまとめて検索できるサイトです。非常に多くの自治体データが検索できますので、まずはここで検索するとよいでしょう。 オープンデータを利用したアプリなども多く紹介されています。参考になるアプリも探すことができるのではないでしょうか。 公共クラウドシステム ジャンルとしては今のところ観光情報だけとなっていますが、APIが用意されており、全データCSVでダウンロードも可能です。一つの観光情報のデータ量としては十分な情報があると思いますが、観光情報としてはもう少し写真が多いと良いので、その辺りは別の情報とマッシュアップすれば良いのではないでしょうか。地方の観光情報を探す点では非常に有益です。 自治体オープンデータ 福岡、北九州を中心としたオープンデータのサイトです。 まだ自治体数が少ないですが、サイトデザインも非常にまとまっており利用者に対して考えられているサイトです。 データセットも多く揃えられており、1時間で更新されるようなリアルタイムなデータも存在しました。 データもCSV形式、Excel形式が多くあり、データの二次編集がやりやすいと思います。 オープンデータの活用事例 防災情報 全国避難所ガイド オープンデータを利用した、全国の避難所データが10万件以上収録されているスマフォアプリです。データベースは随時更新されているようで、一時滞在施設や給水拠点、医療機関などが検索できます。アプリ起動と同時に、現在地からの避難所が表示されるのはとても便利です。 カーリル | 日本最大の図書館蔵書検索サイト オープンデータを利用して、全国の図書館を串刺しで借りたい本を検索出来るサイトです。本のデータベースとなると、重いというような印象を受けますが、カーリルにおいてはそれを払拭するようなスピードとなっており、公共のデータと、民間の技術がマッチした素晴らしい例だと思います。サイト自体でもオープンなAPIも提供されていて、過去には、そのAPIを利用したコンテストも開催されたようです。 オープンデータの今後 日本政府においても、「機械判読に適したデータ形式を、営利目的も含めた二次利用が可能な利用ルールで公開する「オープンデータ」の取組を推進しています。」 日本政府データカタログサイト より抜粋 ここで言う機械判読の定義なのですが、PCなどで表示や閲覧できる方法のことを指しているであろうことから、Excel形式、PDF形式の配布もあるようです。しかし企業などがシステムでデータ活用を行うとすると、データそのものが欲しい場合が多く、これらのフォーマットはとても扱いにくくなります。 情報によっては、CSVなどフラットデータも存在しますが、まだまだその様にまとまっているデータは少なく感じました。 公共データが自由に使える社会となっている現在、自社サービスへの取込、販売促進などなど…これからの益々増えていく政府・自治体のオープンデータを活用するアイデアを生み出して行くことが、さらなるオープンデータの発展を生むことでしょう。

APIですべてのデータを発信することに対して危機感を抱くというのはよくあることです。類似の他社サービスに簡単に乗り換えられてしまうのではないか、乗り換え用の変換ツールを作られてしまうのではないかと言ったことが考えられるでしょう。 しかし利用者視点で考えるとデータエクスポート系の機能はとても大事なものです。そして、それは翻って自社サービスにとってもプラスの価値を持つものになります。 移行するのは簡単ではない いくら機能としてエクスポートができるとしても、実際に乗り換えるというのは大きなコストです。実際に使われるのはサービス自体が終了する時くらいでしょう。 APIを他社と全く合わせて提供するのは困難です。似たような機能を提供するAPIであったとしても、インタフェースは異なるのが一般的です。そのため、サービスを移行したとしても新サービスに合わせた開発は必ず発生します。そうしたコストは決して小さくないため、乗り換えは困難になります。 移行するのはサービスの質の問題 大きなコストを払ってでもサービスを変えようと考えるのはよほどのことです。つまりAPIにエクスポート機能があろうとなかろうと乗り換えたくなるくらいサービスの質に差があるということです。エクスポート機能がない、サービスの質が悪いという状態は利用者にとって大きなデメリットであり、サービスに対して悪い印象しか残らなくなってしまうでしょう。 エクスポート機能が与える安心感 しかしエクスポート機能が提供されているだけで利用者に与える心象は大きなプラスになります。いざとなれば（そのいざは殆どないわけですが）載せ替えできるという安心感がサービスに対する信頼につながります。 バックアップ機能になる APIのデータがきちんと履歴管理されているならばまた違いますが、多くのAPIは最新のデータを返すものが多くなっています。そのため利用者視点で考えるとデータが誤って削除されたり更新されてしまった場合に備えてバックアップを取っておきたいと考えるでしょう。 日々自動的にエクスポートが行えるならば、それがバックアップとして利用できるようになります。載せ替えはしなくとも、バックアップ目的でエクスポートを利用したいというのはよく聞く話です。 選定時のメリット これからAPIを使っていこうと考えている開発者が類似のサービスを見比べた時、エクスポート機能を備えているものとそうでないものがあったとします。その時エクスポート機能を備えているものは大きなアドバンテージになります。 開発者として、データのロックインを嫌います。特にAPIのようにシステムで自動連携、日々データが蓄積されていくものは使い始めたが最後、データは増えていく一方です。それがロックインされているというのは経営上のリスクにもなります。 エクスポートできるということは、最後のハンドリングは自分たちでできるということです。エクスポート機能の有無は選定に大きく関わってくるでしょう。 API提供企業としては一度使い始めたユーザを取りこぼしたくない、逃したくないと考えるのは自然なことです。その結果、データをロックインする傾向にあります。しかし、逆に利用者視点で考えるとロックインされるのはリスクでしかありません。 API提供企業は利用者を増やすためにも、利用者視点でサービスを提供することを考えなければなりません。特に対開発者という視点で考えると、データのロックインは最も避けるべきことと言えます。

今回はAPIのバージョン管理について主なパターンと、既存のソフトウェアで使われるバージョン管理との相違点について紹介します。 パス もっともオーソドックスな方法と言えます。多くの場合、次のようになります。 /v1/users またはバージョン番号を日付で行っているケースもあります。 /2016-06-01/users バージョン番号を持たせるケースの場合、何をもってv2にするかが問題になります。日付の場合、リリースしたタイミング（その日付）を使うので数字の付け方に悩むことはないでしょう。 ただし、これらの方法の場合、 何をもってバージョンを上げるか という問題が常に付きまといます。既存の修正なのか、バージョンアップなのかの区別が判断しづらいということです。できればリリース前にバージョンの付け方をルール化しておくのがいいでしょう。 また、v2を作った場合にすべてのAPIがインタフェースを変える訳ではないという問題があります。usersは変えたとしても、productsやその他のインタフェースはそのままで良いというケースがほとんどでしょう。そうした時に、あるAPIは常に古い日付であったり、逆に更新されていないけれどもバージョンが上がってしまうAPIが出ることになります。 HTTPヘッダー バージョンをHTTPヘッダーに含めるケースがあります。このメリットとしては、パスのように アクセス先を変えないで済む ということです。エンドポイントはAPIのバージョンが上がったとしても変わりません。利用者としては常に同じURLで使えるというのはメリットがあります。 デメリットとしては多くの場合、HTTPアクセス部分は共通化して作られるため、usersはv2、productsはv1といった具合に切り替えるのは簡単ではないということです。特にHTTPヘッダーのような情報は共通化した上で、v1またはv2という文字列で固定されてしまっている可能性があります。 SDKやライブラリです隠蔽する方法も考えられますが、それでもバージョンを指定してもらうというのは余計な手間を増やしてしまうためあまり良いと方法とは言えないでしょう。 クエリー クエリー文字列の中でバージョンを指定する方法もあります。こちらはHTTPヘッダーと同じでエンドポイントは常に同じです。そしてURIのクエリーの中でバージョンを指定します。HTTPヘッダーよりは変えやすい印象です。 この場合、バージョンを固定しておけば返ってくる情報は常に同じという安心感があります。パスで指定するケースに比べて、管理単位が細くなる印象です。 // パスでの指定 /v1/users /v1/products /v2/users // v1とは別なレスポンス /v2/products // v1と同じレスポンス // クエリーでの指定 /users?v=1 /users?v=2 /products?v=1 クエリーでの指定の場合、v=2は存在しないことになります。開発者としては新しいデータ取得法を使いたい場合はv=2を指定し、そうでない場合はv=1を指定することになります。 デメリットとしては共通したアクセスになるので、クエリーでの指定を見てレスポンスを返す分、ソースコードの分岐が増えてしまいます。徐々にソースコードが汚くなるかも知れません。 case params[:v] when '1' // バージョン1を指定した場合 when '2' // バージョン2を指定した場合 end もちろん最初からバージョンアップする前提で作られている場合は綺麗に設計もできるのですが、多くの場合バージョン番号は用意していても使うための仕組みはないケースが殆どです。 一般的バージョン管理との相違 パスにバージョン情報を入れた場合、印象としてはSubversionのような全体でバージョン番号を持ったバージョン管理に近い印象になります。もちろん、更新されていない /v2/productsに対してアクセスがあったら/v1/productsを呼び出すといった形にできますが、利用者としては v1 と v2 で何が違うのかと疑問に思ってしまうことでしょう。ドキュメントにその説明を載せるのも面倒です。 かつてあったCVSの場合、バージョン管理はファイル単位になります。クエリを使った方法はこれに近いものになるでしょう。アクセス先単位でバージョン番号を指定するのはあまり筋が良いとは思いませんが、現実的かも知れません。この場合、アクセス先単位でドキュメントに v1、v2の相違について掲載できるようになります。 Gitのような分散型バージョン管理の考え方をAPIのバージョン管理に適用した場合はどうなるでしょうか。これは2つの考え方ができます。 タグを使った全体の制御 まず大きなリリース単位によってタグを使います。このタグはパスに含めるのが良いでしょう。v1、v2相当になります。 アクセス先単位での細かい指定 さらに細かく動作を指定したい場合はクエリ文字列を使って設定できるようにします。これは次のタグに至るまでの細かいバージョン番号と言えます。基本的にはタグを使ったものだけで十分でしょう。 APIのバージョン管理はあまりうまくいっていないケースが多い印象があります。どのタイミングでバージョンを上げるか、後方互換性をどう維持するか、修正と機能追加の違いは何かといった具合です。 これらは既存のソフトウェアのバージョン管理が参考になると言えます。メジャー、マイナーアップデートなどの考え方、APIの開発計画に合わせてバージョン更新を考えていくのが良いでしょう。多くの場合、一度目のバージョンアップを躊躇してしまうためにずっと同じバージョン番号で更新を重ねてしまうようです。最初のバージョンアップは事前の計画に沿って進めていくのが良いでしょう。

最近のAPIはJSONを基本フォーマットとして提供していることもあり、Webアプリケーションから利用したいという要望が強くなっています。しかしWebアプリケーションでのAPI利用は、サーバサイドとは異なる問題点が幾つもあります。 非同期 Webアプリケーションの場合、基本的に利用する言語はJavaScriptになります。JavaScriptはシングルスレッドな実装なので、ネットワークやデータの処理に時間がかかるものを同期処理にすると、処理が完了するまで全く何も操作できなくなってしまいます。それを防ぐためにJavaScriptは非同期で実行されます。 非同期処理においては何かの処理完了を待ってから次の処理につなぐといった動作をする際にコードがネストしながら書くことになります。現在、Promiseやyield、syncといった新しい技術も開発されてきていますが、APIとのデータ送受信は非同期処理であることを強く意識する必要があるでしょう。 CORS Webブラウザはセキュアな設計を重視しています。そのため表示しているサイト以外のデータを利用するのに対してセキュリティ上の制約がたくさんあります。特にプログラマブルなAjaxについてその傾向が強くなっています。 GETであればJSONPが使えますが、POST/PUT/DELETEといったメソッドについてはサーバ側でCORSがサポートされている必要があります。逆にサーバ側の設計としては無制限にCORSを許可するのはセキュリティ上のリスクになるということを把握しておく必要があります。 キーの隠蔽 APIの利用に際してキーを使う場合、そのキーが漏洩しないように注意しなければなりません。HTMLやJavaScript上に定義するのは問題です。多くの場合、Webサイトのドメインとキーの組み合わせで制御しています。 安全な方法としてはOAuth2でドメインを使って制御するのが良いでしょう。また、提供側としてはトークンの再生成機能を用意しておくのも必要です。 認証 Webアプリケーションではキーの完全な隠蔽が難しいので、認証においても注意が必要です。OAuth2を使うのが良いですが、場合によってはトークン認証を使うかも知れません。トークンが漏洩すると外部からデータ操作が可能になってしまうので注意が必要です。 Basic認証はID/パスワードの入力が必要になるのでお勧めしません。APIと関係なく認証だけを使いたいのであれば、OpenIDを使う方法も考えられます。 コードが公開される JavaScriptの最大の難点としてはソースコードが公開されてしまうことでしょう。難読化することもできますが、逆に可読性を回復させるソフトウェアも存在するので大した意味はありません。 現在、ウェブアセンブリとしてJavaScriptをコンパイルする技術も開発が進められていますが、標準化するのはまだまだ先でしょう。そのためソースコードは誰かに見られても大丈夫なようにしておく必要があります。 Webアプリケーションの場合、サーバサイドで使うのと違う点としては、 利用主体がコンピュータ（サーバ）/人（Webアプリケーション） ソースコードが見られない（サーバ）/見られる（Webアプリケーション） が挙げられます。相違点を適切に把握し、セキュリティに配慮した利用が肝要です。提供側としては、利用主体の違いによって提供するデータであったり、方法を選定する必要があるでしょう。

APIは自動処理であるという点において、セキュリティリスクの大きい技術と言えます。もし認証情報が漏れると、次のようなリスクが起こりえるでしょう。 データを一気に消される プライバシーや機密に関わるデータを一気に抜かれる 違法なデータをアップロードされる 不要なデータが大量に送られる そうした状態を防ぐためにもセキュリティについて十分な配慮が必要です。 1. アクセス制限をかけましょう 企業同士の提携によるAPI利用の場合、IPアドレス単位でアクセス制限しても良いでしょう。そうすることで提携先の企業からの正しいリクエストであると担保できます。 2. 認証をかけましょう 個人や利用者単位であればOAuth2を使い、サーバからのアクセスであればトークンや証明書形式での認証を行いましょう。トークンや証明書は複数発行できるようにし、万が一漏れた時にリニューできるようにしておきます。 3. 通信はSSL/TLS 企業の特定の場所からのアクセスであっても通信はSSL/TLSを使って暗号化処理を行いましょう。パブリックなものでなくとも、クライアント証明書でも良いでしょう。 4. アクセス権限をつけましょう 企業レベルのAPIであれば、トークン単位であってもアクセスできる機能に制限を設けられるようにしましょう。そうすることで、不用意なデータアクセスを避けられるようになります。 5. バックアップをとりましょう APIからのデータ削除処理は処理としては正しいデータ削除となります。データ更新についても同様です。かなりバックアップを取り、データを復旧できるようにしておくべきです。直近のデータ操作であれば、取り消し処理ができるようになっているのが望ましいです。 6. ログを取りましょう 操作ログを残しておくのは監査目的にも重要な意味を持ちます。操作前のデータと操作後のデータを取っておくことで、バックアップにもなるでしょう。 7. 異常なデータ操作を検出できるようにする 不要に大量のアクセスが一気にきた場合、それらを検出して処理をペンディングする仕組みがあります。APIにおいても必要な技術です。 また、最近では機械学習分野が進んでおり、定常的ではない操作が行われた時に通知を出せるようになっています。誰もいないはずの深夜にアクセスがきた場合や、普段行わないデータ検索が行われたといった時に検出できるようになっていると、より早く問題解決につなげられるはずです。 API操作のためのキーが漏洩したりすると、誰も知らない内に大量のデータが消されていたなんて問題になる可能性があります。また、辞めた担当者が外部からデータを閲覧していたということになったらセキュリティ上の大きなリスクになるでしょう。 APIは自動化の仕組みのため、普段運用の中では気付きづらい存在と言えます。だからこそ未然の準備と、検出する仕組みが必要になるのです。

昨今は内部・外部ストレージ、クラウドストレージも格安サービスが増え利用が手軽になり、気軽に大容量データを扱えるようになりました。 サイト内でも画像を手軽にアップロードしたりするサービスは、必須条件といっても過言では無いくらい要求が高まっていますが、それに伴ってデータを整理、分類して、次のサービスアップに繋げることが肝心となっています。 そこで今回は、画像解析を行ってくれるAPIをまとめました。 ※ なお、API仕様や利用料金などは、2016-05-26現在のデータとなっています。 AlchemyVision (IBM Watson) IBM Watsonの画像解析APIです。年齢範囲、男女、テキストなどを取得できます。 複数の人数にも対応していて、かなりの精度で解析が可能です。 しかし、あまりフレーム内に顔が接近していると判別が難しい様子で、これからの精度アップが期待されるところでしょう。 同サービスのVisual Recognitionにマージされたとアナウンスがありましたが、今後このサービスが継続されるかどうかまでは現在の所は説明がありませんので、利用にあたっては注意する必要があるでしょう。 サイトページ： AlchemyVision | IBM Watson Developer Cloud デモページ： Alchemy Vision Visual Insights (IBM Watson) IBM Watsonの画像コレクション解析APIです。 写真のコレクション（Zipアーカイブ）から、人や動物、物、場所等を含め、アクティビティの内容や関心事項の値を解析できるAPIです。 写真1枚を解析するのではなく、コレクション全体の中での占める割合を算出してくれます。 出力内容は、画像イメージの階層構造とスコアリングが中心となっています。 サイトページ： Visual Insights | IBM Watson Developer Cloud デモページ： Visual Insights Visual Recognition (IBM Watson) IBM Watsonの画像解析APIです。 同サービスのAlchemy Visionは、2016年05月20日に、こちらのサービスにマージされたようです。 クラス分類、taxonomy分類、顔検出（性別、年齢範囲、有名人など）の解析が可能です。 Bluemixの１アカウントで、一日あたり250のイベント（画像）まで無料ですが、それ以上は解析内容ごとに料金が変わるので注意が必要です。 サイトページ： Visual Recognition | IBM Watson Developer Cloud デモページ： Visual Recognition Demo Google Cloud Vision API Google Cloud の機械学習による画像APIです。 OCR機能、属性、ランドマーク、顔、ロゴ、有害コンテンツの検知、ラベル(物体)検知などが可能です。 チュートリアルは Google Storage を利用する方法になっていますが、バイトデータを直接送信することもできるAPIとなっています。 課金方法は、機能ユニット単位となっており、例えば顔検知とラベル(物体)検知をした場合、両方の機能の利用分が月額で請求されます。 最大で20Mユニット/月 となっていますが、申請をすれば追加で拡張できるようです。 Google Cloud Vision API Computer Vision (Cognitive Services) Microsoft製の画像解析APIです。 状況説明、タグ付け、アダルトコンテンツ、カテゴリ、カラーなどが解析できます。 有名人などを認識可能であり、世界中のビジネス、政治、スポーツ、エンターテイメントから200000人もの有名人を認識できるそうです。 また、テキスト解析、変わったところではサムネイル生成も可能となっています。 利用料金は5,000トランザクション/月まで無料となっていますので、いろいろと試すことが出来そうです。 サイトページ： Microsoft Cognitive Services - Computer Vision API Emotion (Cognitive Services) Microsoftが提供する画像解析APIで、「怒り」「軽蔑」「嫌悪感」「恐怖」「幸福」「中立」「悲しみ」「驚き」のスコアリングするAPIです。 複数人の解析もカバーしており、それぞれの顔の位置情報も取得できます。 かなり隣接した顔位置でも解析ができるようで、精度も安定しているようです。 利用料金は30,000トランザクション/月まで無料となっています。 サイトページ： Microsoft Cognitive Services - Emotion API Microsoft CaptionBot 最後にAPIではありませんが、Microsoftの画像解析サービスサイトを紹介します。 これは、上記のMicrosoft Cognitive Servicesを組み合わせて作成されているようです。 画像をアップロード、URLなどで指定すると、それについて解析してコメントを返却するサービスとなっています。 このように、APIの組み合わせ次第で面白いサービスができるという一例でしょう。 サイトページ： CaptionBot 最後に 画像解析APIは、各サービスで趣向をこらしているようです。 BigDataを扱うことで、非常に優れたサービスが、大変多く出てきている印象をうけます。 画像解析APIは、アイデア次第でいろいろなサービスに組み込むことができそうです。 ぜひ皆さんのサービスに役立ててください。

APIというのは主に外部の開発者が見ることになります。そしてその設計思想が彼らの思いとマッチしていないと使うのを嫌がられることになります。逆にエレガントで統一性のあるAPIは開発者を刺激し、使おうという姿勢に変えてくれます。 ​ そこで今回は多くのAPIを提供している各社がリリースしたAPIガイドラインを紹介します。 ​ interagent/http-api-design: HTTP API design guide extracted from work on the Heroku Platform API ​ Herokuが実践しているAPIデザインガイドになります。ステータスコード、リソース、タイムゾーン、パスの付け方、バージョニングなど数多くの項目に渡って記述されています。 ​ API開発指針 | EC-CUBE3 ​ ​ 国産Eコマースシステム、EC-CUBE3におけるAPI開発指針になります。日本語で書かれているので分かりやすいでしょう��� ​ これから始めるエンタープライズ Web API 開発 | オブジェクトの広場 ​ ​ エンタープライズAPI設計における注意点がまとまっています。使いやすさ、分かりやすさ、安全性、堅牢性、耐障害性などエンタープライズならではの説明があります。 ​ Web API設計指針を考えた | MMMブログ ​ ​ MMM社によるAPI設計指針をブログで公開しています。URL、レスポンスなどについて記述されています。 ​ WhiteHouse/api-standards ​ ホワイトハウスのAPI標準です。オープンデータを進める上でもこうしたドキュメントが公開されていることで一貫性をもった提供が期待できるはずです。 ​ api-standards/api-style-guide.md at master · paypal/api-standards ​ PayPal社のAPIスタイルガイドです。複雑なオペレーションにおけるリスクとメリットなどは参考になる点がありそうです。 ​ 18F/api-standards: API Standards for 18F ​ 18Fというのは米連邦政府のテクノロジーチームだそうです。彼らのAPI開発におけるベストプラクティスがまとまっています。 ​ refinery29/api-standards: Refinery 29 API Standards ​ ソートやページネーション、モックレスポンス、検索など実用的なAPIにおける標準がまとまっています。 ​ API Design eBook ​ ​ ApigeeによるAPIデザインの電子書籍（PDF）になります。2012年のものですが、内容的には現在でも十分通用するものになっています。電子書籍なのでリーダーに入れて読むのに良さそうです。 ​ API Design Guide — API Design Guide 0.1 documentation ​ オーストラリアのシドニーとキャンベラによるAPIデザインガイドです。開発およびその利用に関する説明があります。 ​ ​ 企業がAPI設計指針を作ると言うことは統一感を作り出すのに大事なことでしょう。また、その設計時においてはここで紹介したコンテンツが役立つはずです。将来的にはこうしたコンテンツをベースにしたLint系ツールが出てくるかも知れません。 ​ 開発者を魅了する、魅力的なAPIを提供するためにも設計のいろはは習得する必要があるでしょう。ぜひ参考にしてください。

プロジェクト管理は企業内での製品やサービス開発を行う肝と言えるシステムです。そんなプロジェクト管理でも数多くのサービスがAPIを公開しています。APIによって基幹システムとの連携も容易になりますので、そういった視点で選定してみるのも良いでしょう。 ​ Wrike for developers ​ ​ OAuthを使ってアプリを作り、それとコネクトします。つまりユーザの権限によって取得できるデータが変わります。コンタクト、ユーザ、グループ、ワークフロー、ファイル、タスク、タイムログ、添付ファイルなど数多くのデータが操作できます。 ​ スペース情報の取得 | Backlog API | Nulab Developers ​ ​ APIキーとOAuthの2つの認証が用意されています。殆どすべての操作についてAPIを介して可能で、データの取得についても柔軟に行えます。Wikiページなども取得、更新できるので外部データを取り込んでWikiを更新するといった操作も行えます。 ​ Trello Developers ​ ​ カンバン系のボード、チェックリスト、メンバー、通知、検索、WebHooksなどの操作ができます。サンドボックスも用意されていますので開発者にとって使いやすいでしょう。 ​ プロジェクト管理SaaS Clarizen（クラリゼン） | NSW ​ ​ 具体的な仕様は契約しないと分かりませんが、他システムとの連携を前提としたAPIが用意されているとのことです。 ​ JIRA REST APIs - Atlassian Developers ​ ​ Atlassianが提供するJIRAのAPIです。WebHooksもありますが、RESTfulなAPIによるデータ公開も行っています。認証はBasic認証またはOAuthとなっています。 ​ Smartsheet 日本語 ​ ​ Excelのようなインタフェースでガントチャートが作成できるサービスです。APIとしてもシートやセルなど表計算のような操作ができるようになっています。WebHooksも提供しています。 ​ Code, test, and deploy together with GitLab open source git repo management software | GitLab ​ ​ オープンソースのGitLabですが、ホスティングサービスも公式に提供しています。元々GitHubを追従して開発されてきましたので、APIのインタフェースや機能もGitHubに似たものとなっています。 ​ Kanban Tool API | Online Kanban Boards ​ ​ カンバンを提供するサービスです。RESTまたはJSONPによるAPIを提供しています。認証はトークンのみとなっています。タスクやタイムトラッキング、レポーティングといったAPIがあります。 ​ ActiveCollab API ​ ​ ActiveCollabはBasecamp対抗馬と言われていたほどのプロジェクト管理で、APIについてもほぼすべてのデータを出力、操作できるようになっています。認証は各ユーザのID/パスワードを使って行うようです。 ​ Rest api - Redmine ​ ​ オープンソースのプロジェクト管理システムですが、APIを提供しています。Redmineをホスティングしているサービス事業者もありますので、そういったところで使うと便利でしょう。 ​ basecamp/bcx-api: API documentation and wrappers for Basecamp 2 ​ ​ Ruby on Rails開発元として知られているBasecamp社（旧37 Signals社）の提供するプロジェクト管理のAPIです。Basic認証のみを提供しています。 ​ ​ プロジェクト管理のAPIとしては、外部や社内リソースから取り込んで新しいページを作ったり、外部のCIサーバと連携したIssueの作成などがよく使われます。さらに出力計としては社内の財務管理システムや顧客管理システムとの連携も考えられます。 ​ APIがあるかないかでプロジェクト管理の使い方が全く変わってきます。業務システムだけにシステム連携の可否は大きな鍵となってくるはずです。

各社がボットAPIをリリースしています。メッセージはテキスト主体のサービスなので、開発がしやすいこと、メッセージを解析することでユーザに自然言語的なレスポンスを返してサービス提供できるのが魅力です。 そこで今回は各社がリリースしているボットAPIをまとめて紹介します。 HipChat - API v2 - Getting started 企業での利用が多いチャットサービスHipChatではREST APIによるメッセージの送信とWebHooksを使ったメッセージの受信をサポートしています。さらにカード型というJSONフォーマットによる特殊なテンプレートも実現します。 Office Dev Center - Skype 世界最大規模のチャットネットワークを誇るSkypeでもボット機能があります。Azure上で簡単にボットが構築できる機能がありますが、APIも公開されているようです。 REST APIs | Twitter Developers TwitterのAPIでは受信に関するWebHooksはありません。その代わりにストリーミングAPIが提供されており、それを使ってリアルタイムにツイートデータを受信できます。ただしキーワードによる絞り込みが必要です。 LINE Developers - BOT API - Overview LINEではWebHooksを使ったメッセージの受信に加えて、スタンプなどの多彩なフォーマットでメッセージが送信できるようになっています。 Bot Users | Slack Slackでは受信のWebHooks、送信のREST APIに加えて、新しいボットを開発する機能もあります。ボットマーケットも整備されており、開発したボットを配布するのに使えます。 Messenger Platform Facebook Messengerでは1対1のコミュニケーションが基本となります。写真などのメディアを受信することができ、送信時にはボタンや写真付きレイアウトを指定することができます。 Bot Code Examples Telegramはセキュリティの高さを謳っているメッセンジャーサービスです。WebHooksを使ったメッセージの受信が可能です。写真やビデオなどのメディア情報が構造的に渡ってきます。 Kik Bot Dashboard カナダ製のメッセンジャーサービスです。ボットショップもすでに整備されています。タイピング情報まで取得できるWebHooks機能があります。テキスト、リンク、ステッカーなどのオブジェクトを指定して送信します。 IMified - IMified API 外部サービスを巡回して、JabberやAIM、SMS、Twitterなどで通知してくれるサービスです。それらのメッセージを受信して別なメッセージを送信するといったボットが開発できるようです。 Webhook | Typetalk | Nulab Developers チームチャットサービスです。WebHooksによるメッセージ受信をサポートしています。ボットに対するメンションだけを送信してくれます。 いかがでしょうか。多くのチャットボットAPIはWebHooksをサポートする形で、似たような形式となっています。一つの形に慣れてしまえば、他のサービスに乗り換えたとしてもボットを開発するのはさほど難しくなさそうです。 ユーザからデータを得て、何を処理するかを考えてみましょう。

最近、チャットボットに人気が集まっています。FacebookがMessenger Platformを発表し、さらにLINEがBot APIを発表しました。さらにSkypeや、よく知られているSlackもボットを開発できます。そこに新しいビジネスチャンスを見いだしている人たちもたくさんいます。 そこで今回はチャットボットを作る際に使われているAPIについて紹介します。 WebHooks 一般的にチャットボットではWebHooksが使われています。チャットに投稿があったタイミングで、あらかじめ指定したURLに対してデータをPOSTしてくれます。ボット側から定期的にデータの存在を確認しにいく必要はありません。これは投稿者（IDのみ）、投稿内容、投稿場所といったデータが含まれています。 一度のWebHooksの中には、複数のメッセージが含まれていることがあります。これは通信量を減らすための工夫です。 ストリーミング WebHooksに対応していない、TwitterのようなサービスにおいてはストリーミングAPIが提供されています。これはTwitterのサーバに持続的な接続を行い、指定したワードを含むメッセージが届く度にイベントが発生します。 技術的に若干難度か高いこと、接続できる数に限度があること（Twitterは1アカウント1接続まで。かつすべてのワードがとれるわけではありません）、サービス自体ベストエフォートであるといった点を考えておく必要があります。 RESTful チャットサービスにデータを投稿するのはRESTfulなAPIによって実現しています。HTTPS通信を使い、指定されたトークンを使ってPOSTするだけです。WebHooksとは切り離せますので、定期的なお知らせ、ツイートなどを流す際には外部からコールしてあげればOKです。 OAuth2 多くのチャットボットではチャットメッセージの中にユーザ情報を含んでいません。そこであらかじめ取得したIDを使ってプロフィールAPIを叩くことになります。この時使われるのがOAuth2です。つまり、投稿したユーザの情報が見られる権限（主にユーザ自身）を使ってプロフィール情報を取得します。Slackのようにグループを基本としている場合は、グループの一員であれば情報が取得できます。 ボットはユーザ情報収集目的に使うと危険性が高いので、プライバシーに配慮しているのだと思われます。 いかがでしょうか。チャットボットもこれまでのAPIによって成り立っています。こうした技術を習得しておけば、ボットの開発はとても簡単に行えるでしょう。逆に提供側としてもこの辺りの技術を使って提供すべきで、独自路線はやめておくべきです。

APIではHTTPステータスコードが大事な意味を持ちます。それによってクライアントではエラーが起きたかどうかを判断します。ステータスコードが200でエラーオブジェクトが返ってくると言うのはとても変な状態と言えます。 そこで今回は主なステータスコードとその使い方を紹介します。 正常系 正常系は200番台で表されることが多いです。 200 OK 最も一般的なステータスコードです。単にOKという意味であったり、アップデートや削除が完了した際にも200を使います。 201 Created 新規作成の場合だけ201としているケースがあります。RESTfulであれば、POSTメソッドだけ201にしていることが多いです。 202 Accepted あまり多くありませんがバッチ処理が受け付けられた場合に返すことがあります。 リダイレクト系 300系のリダイレクトは時々使われますが、APIのURLを変更するのは良い仕様ではないのでお勧めしません。クライアントが自動的にURLを変更してくれなかったり、OAuth2のようにシグネチャ生成の中にパス情報が入っている場合、リダイレクトは生成エラーにつながるでしょう。 301 Moved Permanently 恒久的にURLが変わった場合に使います。 302 Found URLが一時的に変わった場合に使います。これはお勧めしません。 クライアントエラー系 システム側で正常なエラー処理として判断されるものは400番台を使います。 400 Bad Request リクエストが不正な場合に指定します。シグネチャ生成のエラーに用いたりします。 401 Unauthorized 認証エラーの場合に使います。ID/パスワード認証はもちろん、トークンベースの場合でも利用します。 402 Payment Required 決済情報が必要であったり、課金上限を超えてしまった場合に利用します。 403 Forbidden リソースへのアクセス権限がない場合に使います。認証はOKですが、権限が足りない場合は403を使います。 404 Not Found リソースが存在しない場合のエラーとして用います。 405 Method Not Allowed HTTPメソッド（GET/POST/PUT/DELETE/OPTIONS/HEADなど）が許可されていない場合のエラーとして使います。アプリケーション側で実装することもありますが、一般的にHTTPサーバ側での対応になるでしょう。 406 Not Acceptable リクエストヘッダー情報が間違っている場合に使います。mimeが間違っている場合もありますが、シグネチャが間違っていたり、セットすべきヘッダーがない場合も406を使います。 409 Conflict 更新がバッティングしたり、ユニークなIDが重複してしまった場合などに使います。 システムエラー系 500番台は主にシステムエラーになります。アプリケーション開発者が認識していなかったエラーが発生した場合はこちらを指定します。APIとして出さない方が良いエラーです。 500 Internal Server Error 主にCGI系のスクリプトで例外エラーが発生した場合に返されます。 502 Bad Gateway アプリケーションサーバが落ちている時にHTTPサーバが返すことが多いエラーです。 503 Service Unavailable アプリケーションサーバ側で何らかのシステムエラーが発生した場合に返します。 他にもエラーコードは幾つかありますが、主に使うのはここで紹介したコードになるのではないでしょうか。適切なエラーコードを選ぶことで、開発者にとって分かりやすいAPIになります。開発を補助する情報として統一感をもって選ぶようにしましょう。

APIの利用者が増えないという悩みは良く聞くところです。そのために行いたい施策を紹介します。 1. インタフェースを他と合わせる もしすでに同分野においてAPIが存在するのであれば、そこに合わせたAPI設計を選択するという手があります。あえて独自性を貫くのは、あまり良い選択肢ではありません。開発者にとっても似たAPIは乗り換え対象にもなるので、全く別な構成よりは似ている方が手軽と言えます。 ただしGoogleとOracleの裁判で見るように、APIにも著作権が認められようとしています（最終的な判決は執筆時点では出ていません）。完全に真似するのは訴訟リスクを背負うことになるので止めましょう。 2. グローバルに提供する APIは自動化の仕組みであり、使っていくことで国境や言語の壁を越えることが多々あります。そうした中、国内専用というのは、海外を考えた時に別なAPIを探さねばならず、後々面倒になります。利用者としては避けてしまうでしょう。 なるべく制限を設けず、グローバルに提供するようにしましょう。 3. 標準技術を利用する 独自の認証技術やアクセス方式を採用するのは止めましょう。RESTfulであったり、OAuth2.0のようにすでに標準化されている技術を積極的に使いましょう。URL設計や、セキュリティ、通信方式などもなるべくすでに数多あるものを採用するのが良いでしょう。 APIはあくまでも利用者にとって使いやすいものであるべきで、提供側のエゴを押しつけるのはよくありません。標準技術の採用は結果としてメンテナンスしやすく、セキュリティにも強いものになるはずです。 4. ライブラリ、SDKを用意する APIを提供するだけで使ってもらえるわけではありません。APIをもっと簡単に使ってもらえるライブラリやSDKを充実させましょう。ライブラリはなるべく数多くの言語を採用すべきですが、最初は提供側の期待する言語からで良いでしょう。例えばエンタープライズであればJavaや.NETが最初になるでしょう。 SDKはスマートフォンアプリ向けに提供されますが、多くの開発者はよく分からないSDKをインストールしたいとは思っていません。また、SDKのせいでアプリが落ちたりするのは致命的な問題になりますので、テストを十二分に行う必要があります。 5. ドキュメントを充実させる APIドキュメントはとにかくしっかりと作り込んでいきましょう。提供側にとっては当たり前のことであっても、利用者は全く知らないことがたくさんあります。それは利用者が不勉強なのではなく、提供側がその道のプロだからです。 コンテンツを拡充させれば、Googleなどの検索流入も増えていきます。利用者はまず最初にドキュメントをチェックして使えるかどうかを判断します。それだけに力を入れたい部分になります。 6. 質問を受け付ける 利用者からの質問を受け付けましょう。質問はなるべくオープンな場所で行い、コンテンツと一部になるように活用していきましょう。利用者の意見、バグ報告、希望する機能を聞くことで開発計画を柔軟に変更し、役立てるようにしましょう。 7. より短いコードで試せるようにする APIを試すまでのステップはなるべく少ない方が良いです。色々インストールする手間があったり、登録して操作が必要だったりするとあっという間に飽きてしまいます。利用者はそこまでしてAPIを使いたいと思っていません。 オンラインだけで試すことができたり、チュートリアルを使って簡単に結果を確認できるようになっていれば、利用者も次のステップに進みやすくなるでしょう。 8. 宣伝する かつてはAPIをリリースするだけで使ってもらえることがありました。また、大手の企業（Google、Facebook、Amazon、Appleなど）であればリリースするだけで開発者がこぞって寄ってきます。しかし多くの企業はそのようなことはありません。 しっかり宣伝し、一人でも多くの人たちに触れてもらえるように努力しましょう。 9. 分かりやすさ APIの説明を一言で言えるようにしましょう。何ができるのか、何が嬉しいのか、明確になっていないと開発者は理解するだけで疲れてしまいます。彼らにあえて使いたいと思うモチベーションがないことを理解しなければなりません。 基本的にいかなるサービスでも同じですが、APIの場合は開発者が対象であること、画面にぱっと出せる見栄えの良いものでないことなどからより明確に、より短い時間でメリットを訴求できるようになっている必要があります。 特に分かりやすさはAPIを広めるファーストステップとして重要と言えるでしょう。