入口が残念な Web API にならないために ~ Web API の Developer Experience(開発者体験) は、TTFHW から ~

by Jonathan Hikita | 2018年12月19日

f:id:sugimomoto:20181218181123p:plain

※この記事はDevRel アドベントカレンダーの19日目の記事です。

近頃まわりの席から変な叫び声が聞こえてくることがあります。だいたい、叫び声が聞こえてきた後は、Mattermost(OSS のSlack)で「このWeb API のドライバープロトですが、当初1週間で見てましたが1月超えそうです。入り口が遠いです。」という流れです。何の話でしょうか?

弊社、CData Software では100を超えるAPI に向けたドライバー製品を作っているので、エンジニアは多くのAPI に触れています。ビジネス向けのAPI と見れば「とりあえず触ってみる・叩いてみる」というGeek な人ばかりです。そんな際にエンジニアの皆さんを叫ばせるの原因の多くは「入り口が残念なAPI 」、つまり使い始めるに至るまでに時間と労力がかかり過ぎるAPI です。

API のユーザーはソフトウェア開発者です。開発者に心地よく使ってもらう(=Developer Experience を上げる)ために、「Time To First Hello World(TTFHW)」を意識して貰えると嬉しいです。弊社のエンジニアも心安らかになりますし、実際開発が進みやすくなります。

こんなAPI は使いづらい:

f:id:cdatasoftware:20181218143937p:plain
APIあるある 使い始めにくいAPI

驚くかもしれませんが、このようなAPI に頻繁にあたります。Web でAPI ドキュメントを公開していないものや、テストアカウントを取得するまでにNDA に誓約書にパートナーシップにと紙の書類のやり取りが必要なケースもよく見ます。もしくは営業サイドとコンタクトなしでは試用ができないこともあります。

TTFHW とは?

当然、これら以外にもAPI リミットやクエリ・ページング、認証、メタデータ、REST っぽくないメソッド、リソース指向と関数指向の混在などいろいろな叫びはありますが、前述の例は「API を一発目叩く際のDeveloper Experience」についての問題です。これを「Time To First Hello World(TTFHW)」と言います。あるプロダクトを使う際に、環境を準備して"Hello World" を実行するまでにかかる時間というほどの意味です。API を試そうと思った際に、実際に環境を整えてAPI を叩く(リクエストを投げてレスポンスが帰ってくる)までの時間は短くあるべきです。

TTFHW が大事な理由は不確実性のコントロール

背景には、エンジニアの行動規範で「不確実性を減らす。減らすには実際に試す。」というものがあるからです。アイディアとして「このAPI を使ったらXX が実装できそう。」と思ったら、どうするでしょうか?企業の電話番号を探して営業の人に来てもらうでしょうか?そんなことをしたらアポイントだけで数日、実際に来てくれるまでに2週間はかかります。営業の人に説明してもらってもそれを鵜呑みにはできないので、そこから提供企業の技術者にヒアリング項目を繋いでもらいます。やり取りをしているうちに、簡単にひと月が過ぎてしまいます。その結果、当初想定していた使い方ができない場合には、投資したひと月は無駄になります。

それよりも、API を使おうと思ったら、その場で検索して、テストアカウントを取って、とりあえず試す方が現実的です。7~8 割の判断材料は「とりあえず試す」という数時間の作業で得ることができます。これが不確実性の効果的なコントロールの仕方です。

こういった背景からAPI のTTFHW を短くすることは大切です。もしDeveloper Experience が悪いと、ユーザーは離脱してしまうかもしれません。離脱しなくてもユーザーの生産性を損なうことになります。

TTFHW が短いAPI

TTFHW まで30分以内だと大変うれしいです。 実際に30分程度でアカウント取得からAPI を叩くまでを実現できそうなサービスも多くありますのでいくつか紹介しましょう。

Twilio:

電話やSMS をAPI で提供するTwilio。API ファーストだけあって、検索すると一発で出てきますね。しかもドキュメントより先に「無償アカウントページ」が引っかかります。その方が速いです。ドキュメント内にサンプルも充実。トライアルアカウント取得は日本語の動画もあり、TTFHW 短いです。 f:id:cdatasoftware:20181218172022p:plain

jp.twilio.com

SendGrid:

メール配信サービスのSendGrid。申込は簡単ですし、なによりサンプルやチュートリアルが豊富。そして、SDK や外部連携部品が大変豊富かつドキュメントに詳細に記載されています。そしてCData のADO、JDBC、ODBC Drivers も掲載頂いてます。 f:id:cdatasoftware:20181218171654p:plain

APIライブラリ - ドキュメント | SendGrid

Stripe:

インターネット決済サービスのStripe はAPI ファーストですから、当然テストは簡単です。そしてプログラミング言語ごとのサンプルリクエストとレスポンスが全エンドポイント参照できる形になっており、TTFHW どころか実装も相当早そうです。 f:id:cdatasoftware:20181218225135p:plain

stripe.com

kintone:

業務アプリ構築クラウドサービスのkintone は、DX 高いです。ドキュメントが丁寧ですね。しかも開発者アカウントを取得に必要な項目は名前とメールアドレスだけという簡素さ。また、kintone はAPI パートナーが連携実装例を作成し、Developer Network にドンドン投稿しています。API /SDK と初期チュートリアルは自社、細かい連携は外部のエコシステムを上手に使っています。JavaScript プラグインなども大変豊富で、API エコシステムではお手本と言えます。 f:id:cdatasoftware:20181218172129p:plain

developer.cybozu.io

CloudSign:

電子契約書のCloudSign。こちらも検索、申し込みも簡素。ドキュメントはSwagger で書かれているのでスキーマ情報も扱いやすくて便利です。CData の社員は大体Swagger とかOData のAPI とかを見るとキャーキャー言って喜んでいます。なぜってそれは実装しやすいから。API とスキーマについては別の機会に書きます。 f:id:cdatasoftware:20181218172347p:plain app.swaggerhub.com

Sansan:

名刺管理のSansan は2015年のAPI ローンチ当時は実はドキュメントも何もかもクローズドなAPI だったと記憶しています。ところが2018年にAPI ポータルをWeb 上にオープン。大変見やすいドキュメントで一気に使いやすくなりました。Sansan の方に聞いたところ、API ポータルを公開してから問合せやAPI 利用開始企業はクローズドだった時に比べ軽く倍以上に増えているそうです。ユーザーだけではなく、社内でも「使いやすい」「勧めやすい」という声があるとのこと。 f:id:cdatasoftware:20181218233836p:plain

Sansan Open API

TTFHW を短くするポイント

自分がAPI を利用する開発者だったらどうやって使い始めるかを考えてみてください。検索→ドキュメント→アカウント取得→テストという流れですね。流れを邪魔するものは極力排除します。

  • 開発者ポータルがWeb で検索して探せる

  • 開発者ポータルにAPI ドキュメントが公開されている

  • 開発者アカウントがWeb で取得できる(無償)

  • サンプルが提供されている

  • 認証などの初期チュートリアルが提供されている

当然なことを当然に提供するだけです。「営業が必ずコンタクトする」「パートナー以外にはドキュメント公開禁止」などと開発者向けではないビジネスの論理でこれらの流れが邪魔されると急にDeveloper Experience は落ちます。重力を振り切ることが必要です。まずはTTFHW を意識・改善してみるのはどうでしょうか?

最後に:Developer Experience はDevRel でポイントとして語られるテーマの一つです。「API やクラウドサービスの利用開始は簡単かつWeb 完結であるべき」ということもDevRel Meetup Tokyo でTwilio のエバンジェリストの高橋さんが言っていた言葉がヒントになっています。是非、DevRel Meetup Tokyoに参加してみてください。

関連コンテンツ

トライアル・お問い合わせ

30日間無償トライアルで、CData のリアルタイムデータ連携をフルにお試しいただけます。記事や製品についてのご質問があればお気軽にお問い合わせください。