B2BソリューションONDAが「良い」API文書にこだわる理由
API文書をUXの視点でつくる――そう言うと、「でもAPI文書って一般の顧客は見ないでしょう?」と思う方が多いはずです。通常UXとは、ソフトウェアのようなサービスの利用体験を指しますから。ではなぜ、B2Bソリューション企業ONDAがこの方法を選んだのでしょうか?
ONDAは、機会の荒野でイノベーションをつくる
まずONDAのサービスをおさらいする必要があります。ペンションからホテルまで、宿泊施設が快適に運営できる多様なソリューションのなかで、代表的なのが統合販売システムONDA HUBです。
客室在庫と価格を複数の販売サイトと連携し、宿泊施設はAirbnb、Agodaなど複数のOTAに「一度に」出品できます。つまり、施設と販売サイトを繋ぐ中間ブリッジの役割を果たすわけです。なぜこうした技術革新が必要なのでしょうか?
施設と販売サイト間のやりとりは今もオフラインで行われることが少なくありません。施設が販売サイトごとに個別出店すれば、Aサイトで予約が入ったとき、Bサイトの在庫を手動で調整する手間が発生します。タイミングを逃せば、ダブルブッキングも起こりえます。
ONDA HUBはこうした不便をなくし、技術で時間と人手を効率化します。
統合販売システム連携の基礎、API文書
統合販売システムは大きく販売サイト連携と宿泊商品供給連携に分かれ、現在4万件以上の宿泊商品(施設)を擁し、40以上の販売サイトと連携しています。
私が所属するPO(Product Owner、通常はソフトウェアサービスで製品を企画し構築する役割)チームは、統合販売システムの基盤となるネットワーク拡張を目標にしています。より多くの施設を供給するため外部サプライヤーと連携し、供給された施設をより売るため(すでに国内外主要OTAと連携済みですが)多様な販売サイトと繋がることに注力しています。
**この過程で中心となるもののひとつがAPI*文書です。**システム連携作業はAPI文書を理解することから始まるからです。
*ここで少し、APIとは?
Application Programming Interface(アプリケーション・プログラミング・インターフェース)の略で、2つのソフトウェア構成要素が相互に通信できるメカニズムを指します。リクエストとレスポンスを使って通信する方法を定義し、API文書にはこれらリクエストとレスポンスを構成する方法の情報が含まれています。(出典:AWS)
つまりAPIは、企業対企業(または部署対部署)がデータをやり取りできる1つの出入口です。
ONDA APIの核心は、施設情報を取得して販売サイトに送り、サイトで生成された予約を再び施設に伝える仕事です。そのため、宿泊商品サプライヤーまたは販売者とどのようにデータを伝達するか約束した内容をAPI文書で確認できます。
**しかし、他者が書いたAPI文書を理解するのは簡単ではありません。**どんなAPIがあって、どう動作し、どんな結果を返すかというスペック(仕様)は会社ごとに異なるからです。さらに英語や数字で構成された文書なので、API文書を初めて見る人には理解が難しいでしょう。
そうなると、API文書について説明し文脈を伝える作業に最も時間を費やします。この文書を理解するため質問と回答のやりとりが何度も繰り返されるのです。
コミュニケーションコストを削減する選択、ReadmeとOAS
したがって、コミュニケーションコストを削減し効率的に連携するには、文書のフォーマットが非常に重要です。明快な言語で文書を作成し、パートナーが直接テストできれば、協力パートナー(ONDAにとっては販売者とサプライヤー)のリソースを節約できるだけでなく、コミュニケーションエラーから生じる問題を事前に防げます。
多くのサービスを試行錯誤した結果、最終的に「Readme」というツールを使っています。APIを設計・開発する方ならよくご存じでしょう。単にAPIスペック(仕様)を見やすく文書化するだけでなく、パートナーが直接テストでき、文書の理解度を高められることが最大の利点でした。
たとえば外国人にキムチチゲの味を説明するとき、「キムチから染み出た汁で辛くて旨みがある」と言葉だけで説明しても理解しづらいですが、一度食べてもらえばすぐに味がわかりますよね。同様に、複雑なAPI文書を最初から全部読むより、文書内で実際に呼び出し(Request)、応答(Response)できるようにしたのです。
もちろんReadme導入初期は困難がありました。同じ産業でも業者やシステムごとに使う用語が少しずつ異なるため、応答(Response)の各項目(Response Body)について説明とタイプを明示する必要があったのですが、Readmeが提供する基本エディタでは限界があったのです。
韓国最大手暗号資産取引所「Upbit」も同じ問題を抱えていたのか、文書本文で応答(Response)を長文で記述する方式を選んでいました。しかしこれは、良い事例と思われる「Airbnb」の方式に比べると物足りませんでした。
- 表で整理され理解に困難はないが、実際の応答(Response)部分は明示されておらず構造を把握するには限界がある。
- 各項目が何か、形式は何か、どんな項目が入るかの例などを表記しており、文書を行き来せずとも理解しやすい。
2つの文書の違いは、Readmeが提供する基本エディタを使うか、それともOAS(OpenAPI Specification)という一種の標準スペックを使うかです。
OASは簡単に言えば、RESTful API(2つのコンピュータシステムがインターネットを通じて情報を安全に交換するために使用するインターフェース)を明示するための標準です。この標準の最大の利点は、言語に依存しないjsonとyaml形式を利用するため、すべてのサービスで誰でも利用できることです。(詳細説明が必要な方のためリンクを残します)
私たちにとっては、販売者やサプライヤーとAPI連携する際に会う開発者、またはPM(Product Manager)が顧客なので、良いUXの観点から製品を提供すべく、応答(Response)の各項目を直感的に見られるようOAS形式に合わせてアップロードする方法を選びました。
良いAPI文書をつくるために導入したもの
企業ごとにAPI文書を残す方式や主体は少しずつ異なるでしょうが、ONDAではPOが中心となって管理しています。サプライヤーや販売者と対話する主体でもあり、内部開発者と協業する際も具体的な明示が必要だからです。
開発者ではないPO、PMがOAS形式に従って良いAPI文書を作るため、何を導入したのでしょうか?
✔️ yaml
OASは開発言語に依存しないyamlとjson形式を利用します。yamlとjsonはデータ転送時のフォーマット規則ですが、jsonは[]や{}といった文字があって少し複雑な印象です。チームメンバーはある程度開発理解があるので、どちらを選んでも構いませんでしたが、開発言語に慣れていない方のため、人間に親和的な形式のyamlを選びました。
✔️ vscode
Swagger Editorのような簡単なOAS作成を支援する優れたツールはすでに存在していました。しかし協業やより簡単な利用のためには、OAS作成以外にもより良い機能を提供するツールが必要で、vscodeが適していました。いくつかのExtension(拡張プログラム)により、OAS文法をよく知らない人も問題を最小限に抑えられるからです。
✔️ github desktop
継続的な管理のためには協業が最も重要なため、githubにOAS作成コードをアップロードしています。開発に慣れた方はvscodeでCLI(コマンドラインインターフェース、ユーザーがテキストで作業命令を入力するとコンピュータも文字列で出力)を利用するでしょうが、これもGUI(グラフィカルユーザーインターフェース、入出力などの機能をわかりやすいアイコンなどのグラフィックで表したもの)でできるアプリをダウンロードし、より直感的に作成・共有しています。
90%以上減った質問
単にスペックを明示するのではなく、1つの製品の観点から既存のAPI文書を改善した後、連携開始時にこれを詳細に説明しなくなりました。質問が来ても文書にすぐ反映し、繰り返し質問が行き交うことが著しく減りました。以前と比べれば、ほぼ90%以上質問が減ったのです。
もちろん、複数文書を管理せず明快に説明できることで、社内満足度も高くなりました。
残念ながら、旧型の運営システムを使うパートナーと協力すると、API文書をPDF形式で渡されることもあります。単にツールやフォーマットを超えて、パートナーを顧客として扱いUXの観点からどんな文書を届けるかは、今後も非常に重要です。パートナーと素早く連携するほど、私たちのネットワークが拡大する速度も速くなるのですから。