API 設計とは

API 設計はアプリケーション・プログラミング・インタフェース (API) を開発するプロセスで、API はアプリケーション機能を公開して開発者およびユーザーが使用できるようにするものです。API は先進的な組織にとって重要で、運用や製品からパートナー戦略まで、あらゆるものに新しい機能を追加しています。今や、ほとんどの組織が API プログラムを導入すべきかどうかではなく、どのように導入すべきかを検討する段階に入っているといっても過言ではありません。

効果的な API プログラムとは、組織全体をカバーする企業戦略をベースに構築し、企業の目的達成を補助するものです。次の 3 つの質問に明確な答えを出せたそのとき、優れた戦略を確立できるようになります。

1. なぜ API を実装するのか (理由)
2. 実装した API から具体的にどのような成果を得たいのか (目的)
3. 成果を達成するために、API プログラムをどのように実行する予定か (方法)

理由

これは、いろいろな意味に誤解されやすい質問です。まず、API そのものの価値に注目するのではなく、API の効果の価値について考えることをお勧めします。重要なのは組織のコアビジネスであり、API が重要であるとは限らないことに注意してください。API が重要となるのは、組織がもたらす既存の価値へアクセスする、新たな種類の方法を提供する手段となる場合です。

もう 1 つのよくある誤りは、API に価値を持たせるためには、ユーザーがその代金を支払う必要があるという解釈です。これが成り立つのは API 自体が製品である場合だけです。ほとんどのモデルでは、これはあてはまりません。API は一般に、売上、アフィリエイトの参照回数、ブランド認知度など、他のメトリクスを伴います。API が持つユーザーへの価値は、API 呼び出し (サービスの要求と応答) の結果であり、呼び出しそのものではありません。

API プログラムを推進するビジネス面での最も一般的な要因は、Cutter Consortium と Wipro が 152 の組織を対象として実施した調査によると、新しいパートナーシップの開発、収益の増加、新しいビジネスモデルの探求、市場投入までの期間の短縮、新しい流通チャネルの開拓です。テクノロジー面での最大の推進要因は、アプリケーション統合の改善、モバイル統合の改善、そして接続をサポートするデバイス数の増加です。API への投資は組織にとって明らかな決定だと納得させるには、組織へのメリットは十分に強固でなければなりません。

目的

2 番目の質問は、「実装した API から具体的にどのような成果を得たいのか」です。言い換えれば、「実際には API は何を実行し、広い意味でビジネス戦略にどのような影響を与えるか」ということです。

組織を内部と外部の両方から考察すると、API の目的を定義しやすくなります。内部から考察されるのは、組織が所有する価値のある個別の資産です。提供されるサービスとリソースの価値と独自性が高いほど、API プログラムの対象として適しています。

独自のデータを持つ組織は、API を介してデータへのアクセスを許可することで、このリソースを活用できます。独自のコンテンツ、データ、サービスによって、API へのアクセスの価値が非常に高くなります。

API がビジネスに対して何を行うべきかを決定するには、内部の視点と外部の視点から考察する必要があります。
目的についての決定は、通常はこの 2 つの視点を組み合わせて行われます。

現場においては、理由が変わることはそれほどないのですが、目的は、市場、技術的な検討事項、経済状況などの外部要因によって大きく変化することがあります。資産の価値についての内部の考え方が変化し、API で達成する内容に影響することもあります。

方法

最後の質問、「成果を達成するために、API プログラムをどのように設計するのか」とは、実装と実行に関するものです。

チームは次の事項を検討する必要があります。

• API の構築にどのようなテクノロジーを使用するか
• API をどのように設計するか
• API をどのように保守するか
• API の組織内部への普及、または外部への公開は、どのように行うか
• どのようなリソースを利用できるか
• チームに誰を参加させるか
• 設定されたビジネス目標に対する達成状況をどのように追跡するか

API チームは「プロダクト」チームに非常によく似ています。顧客が社内であっても社外であっても、他のユーザーが利用するインフラストラクチャを構築、デプロイ、運用、最適化する責任を負っています。

プロダクトチームと同様に、API チームもさまざまな人材から構成されています。代表的なチームには、戦略と目標の達成に向けて舵を取る製品中心の担当者、API 設計のベストプラクティスを保証する設計重視のチームメンバー、API テクノロジーを適用するエンジニア、API を実行する運用チームメンバーが参加します。

作業を進めていくうちに、サポートおよびコミュニティのチームメンバー、API エバンジェリスト、セキュリティ担当者など、他のメンバーを追加することもできます。

John Musser 氏は 2012 年 O’Reilly Open Source コンベンションでの講演で、優れた API を実現するための 5 つの「鍵」を紹介しました。

1. 価値あるサービスを提供する
2. 計画を練り、ビジネスモデルを用意する
3. シンプルかつ柔軟で、導入しやすくする
4. 管理し、測定する
5. 優れた開発者向けサポートを提供する

最初の鍵である価値あるサービスの提供は、API プログラムの理由を考える際に特に重要です。価値提案は、API を成功させるための主な原動力です。API の価値提案が間違っている (またはまったくない) と、ユーザーを見つけるのが非常に困難になり、不可能にさえなります。

デジタルであれ物理的であれ、既存の製品を持つほぼすべての企業が、API から価値を創出できます。
ただしそれは、API が既存の製品にリンクして機能を強化する場合です。開発者にとって意味のあるユースケースに対応するように API が構造化されている限り、価値はもたらされます。

API の価値を見出して記述する作業は、反復を伴うプロセスです。最初のステップは、ユーザーが実行しようとしているジョブを記述することです。以下に例を示します。

• 非常時に緊急連絡をチームメンバーに自動的に送信する
• 重要なファイルを損失しないよう、バックアップする
• 特定のイベントを検出するためにサンプルデータを収集する

次のステップは、ジョブを実行しようとする前、実行中、実行後にユーザーに影響を与える、特定の問題を突き止めます。

• 複数回の試行で送信の信頼性を確保する、障害を検知する、1 件だけでなく多数のメッセージの送信を考慮する、ユーザーの位置に応じて複数のメッセージ配信システムを統合する
• ファイルを安全に配信し、同時に転送帯域幅を最小化する
• 膨大な量のデータを扱い、リアルタイムでの照合を試みる

3 番目のステップは、ユーザーにとっての潜在的なメリットをまとめることです。

• 脅威の警告ではない、オポチュニティにつながるその他の種類の通知を送信する
• 必要な信頼性が確保されているなら、他のストレージ機器を取り外す
• イベントに応じて自動的にアクションをトリガーする

このような改善したいポイントを考察する場合、視野を広げて考えて、サポート、文書、開発者ポータルなど、ユーザーが利用する可能性があるすべてのものを列挙します。次に、ジョブを完了する前後や作業中に API ユーザーの妨げとなる物事、またはユーザーの作業を妨害する問題を除外または軽減するために、どのような方法を取るか、概略を考えます。そして、あらゆる種類の API ユーザーにとっての利点をどのように実現するかを記述します。

このプロセスを実施すると、上記の 3 つの例は以下のようになります。

• 1 回の呼び出しでメッセージを配信し、到着が保証されるまで自動的に再試行できる、マルチチャネルのメッセージング API (Twilio や PagerDuty など)
• 新しいバージョンを同期するかどうかを、最適化された呼び出しで効率的にチェックする、同期 API (Bitcasa や Box など)
• 複数のデータソースを構成可能なストリームに集約し、フィルタリング、サンプリング、容易な操作を可能にする API (GNIP や DataSift など)

最後に、API がユーザープロファイルに適合していることをはっきり表現する、いくつかの説明文を記述すると、作業の明確化に役立ちます。このような適合性の説明文を書くのが難しいなら、その API モデルはもう一度見直す必要があるでしょう。おそらく、追加、変更、改良、または削除が必要な API 機能が見えてくるはずです。また、API には優れた価値があっても、ターゲットとしているユーザーの種類に適していない場合もあります。

適合性の説明を要約して 1 つの包括的な説明文に凝縮させれば、それが API の価値提案となります。上記のメッセージング API の例については、以下のようになります。

メッセージング API はエンタープライズ開発者に、非常に重要なビジネスアプリケーションに対する、信頼性があり、到達が保証され、遅延のないテキストメッセージ機能を提供する。また、API は普及している大半のプログラミング言語に対応しているソフトウェア開発キット (SDK) によってサポートされているので、すばやく統合できる。

場合によっては、「これはあまりに大げさだ。内部向けの API を作るだけなのに」と思うかもしれません。それでも、価値を重視する姿勢は、内部ユースケースについても大切です。価値提案の検討が不十分なままでは、API の価値を他のチームに売り込むのが困難になります。価値提案がきちんと定義されていれば、導入が容易になり、API プログラムはビジネスにとって重要な貢献をします。

独自の API プログラムの価値を定義するには、以下の 5 つの質問を検討してみます。

1. ユーザーは誰か：この質問へは回答は、ユーザー (既存の顧客、パートナー、外部開発者)、ユーザーの役割 (データサイエンティスト、モバイル開発者、運用担当者)、要件や優先事項との関連性を考慮します。
2. 解決しようとしているユーザーの求める改善ポイントは何か、API で提供しようとしているメリットは何か：この質問への回答は、顧客のビジネス、価値提案で定義される課題と利益、重要なニーズ (改善ポイントへの対応、収益のチャンス) に対応しているかどうか、ユーザーのどのメトリクスが改善されるか (速度、収益、コスト削減、新しい機能の実現) との関連性を考慮します。
3. API でサポートされるユースケースは何か：価値提案を活用して、組織やユーザーにとって最も効果的な、API から生まれる課題やチャンスに対するソリューションを特定します。このようなユースケースに対処するように API を計画します。
4. どのようにユーザーに対する価値を拡張していくか：将来的な変化を念頭に、価値提案を計画します。つまり、内部または外部の変化に関する今後の重要なマイルストーンは何かということです 。
5. 組織に対して内部的にどのような価値が生み出されているか：内部的なメリットと、社内で API がどのような価値をもたらすかを検討します。

API の価値を明確に説明できたら、API ベースのプログラムを設計する準備が整ったと言えます。ただし、API にはコストも伴うので、価値とのバランスを取る必要があります。価値は金銭的に測定することができないことがありますが、次のようにコストは現実的なものです。

• 組織の既存のコアビジネスは何か
• API をどのように使用してこのビジネスをスピードアップまたは強化できるか

時には、API によって、組織の既存のビジネスモデルの範囲外にあるまったく新しいビジネスチャンスが導かれることがあります。しかしこのような場合でも、新しい方法で実行するために、一般には既存のアセットや知識を活用します。

まとめると、効果的な API プログラムの設計にとって適切なビジネスモデルを決定することがなぜ重要なのか、理由は以下のとおりです。

1. 適切なビジネスモデルを決定すると、組織にとっての API の価値の重要性が認識され、API プログラムへの長期的なコミットメントに関する意思決定が促されます。コミットメントがなければ、効果的な API プログラムを確立して実行するために必要なタスクを完了させるリソースを十分に配置できません。
2. 適切なビジネスモデルの決定は、製品の機能の定義に役立ちます。定義は第三者を納得させ、ビジネスを創出するために必要です。
3. 適切なビジネスモデルを決定すると、組織内の役割と責任に関する検討、および API が生成する価値のどの部分を誰が保持するかについての考察が行われます。また、API のユーザーは API を使用することで何を獲得し、それに対して API プロバイダーが獲得するものはどのように調整されるかも定義されることになります。

優れた API 設計にはいくつかの中心となる原則があり、実装によって異なります。例えて言えば、どの車にも、ハンドル、ブレーキ、アクセスがあります。ハザードランプ、トランクオープナー、ラジオなどは多少の違いがあるかもしれませんが、運転の経験を積んだ人なら、レンタカーを運転する方法がわからないということはまずありません。

優れた API チームは、このレベルの「運転しやすい」設計を目指します。すなわち、経験を積んだ担当者が使用するとき、説明がほとんど不要な API です。

シンプルさ

API 設計のシンプルさは状況によって異なります。ある設計があるユースケースにとってシンプルであっても、別のユースケースにとっては非常に複雑となることもあるので、API メソッドの粒度を調整する必要があります。シンプルさについては、次のような複数のレベルで検討すると考えやすくなります。

• データ形式：XML、JSON、プロプライエタリー形式、またはこれらの組み合わせ。
• メソッドの構造：メソッドは、幅広いデータセットを返す汎用性の高いものから、目的の要求に絞った特殊性の高いものまで、さまざまです。また一般に、特定のユースケースを実現するために特定の順序で呼び出されます。
• データモデル：基盤のデータモデルは、API を介して実際に公開されるものと非常に似ていることも、まったく異なることもあります。この点は、使用しやすさとともに保守しやすさに影響します。
• 認証：認証メカニズムには、それぞれに異なる強みや弱点があります。どれが最も適切かは、状況によって決まります。
• 使用方法のポリシー：開発者の権限とクォータは、分かりやすく、使いやすくしなければなりません。

API をシンプルにすることは、柔軟にすることと両立させにくい場合があります。シンプルさだけを念頭に置いて作成された API には、過剰にカスタマイズされるというリスクがあり、非常に限られたユースケースにしか対応できず、他の用途に使用する自由度がなくなります。

柔軟性を確保するには、まず、基盤のシステムとデータモデルを含めて、運用の基礎となる空間を見つけ出し、これらの運用のサブセットのうち実現可能で価値があるものを定義します。シンプルさと柔軟性のバランスを適切に調整するには、以下のようにします。

• アトミック操作の公開を試みる：アトミック操作を組み合わせると、処理対象の全体をカバーできます。
• 最も一般的で価値のあるユースケースを突き止める：複数のアトミック操作を組み合わせたメタ操作による 2 番目のレイヤーを設計し、これらのユースケースに対応します。

議論の余地はあるものの、アプリケーション状態のエンジンとしてのハイパーメディア (HATEOAS) のコンセプトによって、柔軟性をさらに向上できます。API およびクライアント操作においてランタイム変更が可能になるからです。HATEOAS は、バージョン管理や文書化を容易にすることで柔軟性を向上させはしますが、API 設計に適用する場合は、細部にわたる検討が欠かせません。

API 設計を熟慮するには、以下の 5 つの質問を検討してください。

1. 対象のユースケースをサポートするように API を設計したか：主なユースケースを特定した後の次のステップは、これらのユースケースをサポートするように API を設計することです。頻度は低くてもイノベーションの実現のためにはサポートすべきユースケースを除外してしまわないようにするには、柔軟性が重要です。
2. RESTful を意味のある形で使用しているか：RESTful API はとても流行っていますが、だからといってこのトレンドに流されてはいけません。RESTful に適しているユースケースもありますが、GraphQL などの他のアーキテクチャスタイルのほうが適しているユースケースもあります。
3. データモデルの公開にあたって、ユースケースを無視していないか：API は、実際のデータモデルから抽象化したレイヤーでサポートする必要があります。原則として、API にデータベースへ直接アクセスさせてはいけません。アクセスが必要な場合であっても、避けるべきです。
4. どの地理的な地域が最も重要で、その重要性に従ってデータセンターを計画しているか：API 設計は、レイテンシーや可用性など、技術以外の要素も考慮しなければなりません。ユーザー数が最も多い場所に地理的に近接したデータセンターを選択してください。
5. API 設計を他の製品と同期させているか：開発している製品がAPI だけではないなら、API 設計が他の製品の設計と連携していることを確認します。API 設計を他の製品から完全に切り離してしまうという方法も考えられますが、そのような場合でも、API 設計をほかの製品から切り離すという計画を、内部および外部にはっきり伝達する必要があります。

API 設計を改善して導入を容易にするための主なメトリクスは、Time To First Hello World (TTFHW) です。このメトリクスは、開発者が API で実用最小限の製品を開発するまで、どれだけ時間がかかるかを示します。開発者の立場になって、API をテストし、ある機能を行うには何が必要かを考えるのは良い方法です。

TTFHW メトリクスの開始時と終了時を決定するとき、開発者の作業プロセスに関わるできる限り多くの面を対象とします。その後、できるだけ迅速で便利になるよう、最適化します。

プロセスをすばやく処理できると、開発者は API がうまく組み立てられているという確信が得られ、物事が予期したように進む可能性が高くなります。「成功の瞬間」までの時間が長すぎると、開発者を失ってしまう危険性があります。

TTFHW の他にも、Time to first profitable app (TTFPA) というメトリクスをお勧めします。「収益性」は API およびビジネス戦略に応じて定義が異なるので、少しやっかいです。とはいえ、API プログラムの一部としての API 処理に関する事項を考えることができるので、検討に値します。

開発者の操作性を考慮する基盤として、次の 2 つの原則があります。

1. 開発者にとって明確な価値をもたらし、明らかな課題またはチャンスに対処する、製品またはサービスを設計します。金銭的な価値に加えて、対応範囲、ブランド認知度、カスタマーベース、間接的売上、開発者の評判などの向上や、さらには、役に立つ優れたテクノロジーを使用するという純粋な喜びにもつながります。
2. 製品は容易にアクセスできるようにする必要があります。これには、登録メカニズムを軽量にする (または撤廃する)、テスト用機能へのアクセス、マニュアルの改良、整理された無料のソースコードを大量に用意するなどが該当します。

API の公開先が一般、パートナーのみ、社内のみのいずれであっても、ほとんどの API プログラムには開発者プログラムを取り入れることをお勧めします。ユーザーに応じて、準備作業のレベルは多少異なります。

開発者ポータル

開発者ポータルは、開発者プログラムの主要な要素です。開発者が API に登録、アクセス、使用する入口となります。API へのアクセスは開発者にとって、シンプルで手間いらずにするべきで、すぐに使い始められるようにしなければなりません。

TTFHW はこの点を評価するために最適なメトリクスです。また、サインアッププロセスの効率化も検討すべきで、単純化してすばやく処理できるよう、改良します。推奨するベストプラクティスは、そもそもサインアップを行うことなく、開発者が API を呼び出して動作 (要求と応答) を試せるようにすることです。また、「はじめに」ガイド、API リファレンスマニュアル、ソースコードなどの補助コンテンツがあると、すぐに習得することができます。

エコシステムパートナーによる迅速化

API プロバイダーは、パートナーとベンダーのエコシステムに参加しています。このようなパートナーは多くの場合、独自のコンテンツ配布およびコミュニケーション・ネットワークと手段を持っています。提携関係を特定すると、API の導入を広めるために効果的です。一般に、API が相補的で、組み合わせることで開発者に価値がもたらされる場合に、このような提携関係が生まれます。

開発者にとっての使い勝手を評価するときに検討すべき質問

1. 最初の 5 分間で API の価値をどのように説明するか：API の価値提案について開発者に訴えかける「セールストーク」を作成します。
2. TTFHW と TTFPA の値、およびどのようにしてそれを短縮するか：これは、エンドツーエンドの TTFHW を考慮することで、API が開発者にとって使いやすくなるように改善する、優れた方法です。開発者の操作性 (ポータルなど) に追加されたすべての要素と、変化するあらゆる API の観点を検討するときは、常に TTFHW と TTFPA のメトリクスを考慮することをお勧めします。
3. 開発者の登録プロセスはどのようなもので、可能な限り簡素化されているか：これは API のユースケースと調整されている必要があります。セキュリティのレベルは、機密性の高い API やデータアクセスに対して強化する必要があるのはもちろん、おそらくより公式の同意が必要になります。その他の場合、早期の開発者を成功させる (TTFHW) には、シンプルで単純なものにします。
4. API を開発者にとって魅力的にするため十分な柔軟性を残しているか：正しい価値提案を見つけ、開発者が API に登録してもらうのが目的です。開発者の成功を支援することで、ユーザーを維持して増やすことができます。
5. 問題が発生した場合、開発者をどのようにサポートするか：拡張性を持つセルフサービス・アプローチが効果的です。多くの開発者の質問は、優れたマニュアル、FAQ、フォーラムで対応できます。しかしセルフサービスには限界があり、詳細情報が必要な質問や、請求書の問題などの複雑な状況については、何らかのサポートメカニズムを用意する必要があります。
6. イノベーションをサポートできるマニュアルがあるか：通常のユースケース以外の処理をしたり、何か新しいことをしようとする開発者には、どのようなサポートがあるでしょうか。優れたアイデアはどこからでも湧き出てきます。