デモフロントエンド

モチベーション

うまく機能する開発チームの重要な実践の1つは、構築している製品の最新の改善点を定期的にデモすることです。製品にユーザーインターフェースがある場合、デモは自然にUI自体を通じて提供され、会議に出席している利害関係者が直接操作できるようにすることもできます。

しかし、製品がAPIの場合どうでしょうか？通常、バックエンドとフロントエンドは同じチームによって開発されることをお勧めします。これは、2つの別々のチームが調整しなければならない状況と比較して、通常、より高い品質とより短い開発時間につながるためです。ただし、これが不可能な場合もあります。バックエンド（API）が、そのAPIを通じてサードパーティへのアクセスを販売する会社によって開発される場合があります。例としては、eコマースサイトが顧客から支払いを受け取ることを可能にする「決済ゲートウェイ」APIを提供する金融機関、または価格比較エンジンとインターフェースするAPIを介して価格比較エンジンが呼び出すサービスプロバイダーなどがあります。

APIに自然なユーザーインターフェースがない場合、意味のあるデモを提供することが困難になります。チームは、APIによって返されるJSONコードを表示することでAPIの使用法を示そうとすることもありますが、これは、特に技術に詳しくない利害関係者にとっては理解しにくいものです。そして、ビジネスの利害関係者が製品を使用することはほとんど不可能になります。

このような状況では、APIデモの目的でシンプルなUIを開発することが有益であることがわかりました。UIは凝ったものでも特に見栄えが良い必要はなく、専用のビルドを設定する必要もありません。目的は、APIの使用を示すことを簡単にすることです。

このようなデモフロントエンドの利点は、デモ中にソフトウェアを展示することに限定されません。一度利用可能にすると、開発者はコードをリポジトリにプッシュする前にローカルマシンで新しい機能をテストするために使用し、品質アナリスト、製品オーナー、その他の利害関係者はテスト環境で製品をテストするために使用します。また、アクセスを購入することに関心のある潜在的なパートナーにAPIの使用法を示すためにも使用できます。デモフロントエンドは、使い続けられる贈り物です。

実践的なアドバイス

デモフロントエンドは、関連するAPIが利用可能なすべての場所ですぐに利用可能である場合に最適です。たとえば、Spring Bootアプリケーションでは、`src/main/resources/public/testdrive`フォルダに静的なHTML、CSS、JavaScriptのアセットを配置して、たとえば`https://localhost:8080/testdrive/`でブラウザを開いてアクセスできるようにすることができます。最も単純なデモUIは、Postmanを置き換える以上のことをほとんど行いません。

図2：ユーザーはリクエストペイロード、メソッド、パスを調整できます。レスポンスは下側のウィンドウに表示され、成功したレスポンスを示す緑色で表示されます。

図3：エラーレスポンスは、出力テキストエリアをピンク色にすることでより明確になります。

デモUIは、特定のAPIエンドポイントに対して有効なJSONリクエストを準備し、ユーザーがテストしたい内容に合わせてリクエストを手動で変更できるようにします。ユーザーがボタンを押すと、HTTPステータスコードと関連するヘッダーと共にレスポンスが表示されます。

現時点では、入力と出力の両方としてJSONを表示していますが、ユーザーに提案されている入力JSONの静的バージョンを増強または変更するために自動化を使用できるという点で、Postmanよりも大きな利点があります。たとえば、有効なリクエストに一意の識別子が含まれている必要がある場合、短いJavaScriptのスニペットで、ユーザーの手間をかけずにランダムな識別子を生成できます。ここでは、UIが最小限の摩擦で迅速なテストを可能にすることが重要です。

このようなデモフロントエンドを作成するために必要なJavaScriptは最小限です。現在のJavaScriptは、特定のライブラリを必要とせずに十分強力ですが、開発者はhtmx、jQuery、またはインラインReactなどの軽量ツールを使用すると便利だと感じるかもしれません。専用のビルドの設定は避けることをお勧めします。これにより、APIの実行とUIを介したテストの実行の間に余分な手順が追加されるためです。理想的には、実行したい唯一のビルドはAPI製品自体のビルドです。何かをテストしたいという願望と実際にテストを実行する瞬間の間の遅延は、開発ループを遅くします。

このようなUIの自然な進化は、

1. さまざまな種類の入力を生成する機能を追加すること。おそらく、JSONテキストエリアを適切なHTMLフォームに完全に置き換えること。
2. 理解しやすい方法で出力を解析して表示すること。

たとえば、旅行関連のAPIがあり、日付を柔軟に変更できる旅行者にとって最高の料金を見つける目的でフライトを予約できます。検索を実行し、価格の組み合わせのリストを返す初期APIがあるかもしれません。入力JSONは次のようになります。

{
  "departure-airport": "LIN",
  "arrival-airport"  : "FCO",
  "departure-date"   : "2023-09-01",
  "return-date"      : "2023-09-10",
  "adults"           : 1,
  "children"         : 0,
  "infants"          : 0,
  "currency"         : "EUR"
}

デモUIは、入力テキストエリアにサンプルペイロードを読み込むため、ユーザーは正確な構文を覚える必要がありません。

図4：実際のJSONペイロードは複雑になる傾向があります。

ただし、ユーザーは日付を変更する必要がある場合があります。静的な出発日または到着日は、時間が経過して日付が過去になったため、最終的には無効になり、日付の変更には時間がかかり、手動によるエラーのためにさらに時間が失われる可能性があります。1つの解決策は、JSONの日付を自動的に変更し、たとえば30日先に設定することです。これにより、APIの簡単な「スモークテスト」を実行するのが非常に簡単になります。「フライトを検索」をクリックして結果を確認するだけです。

さらに一歩進めることができます。たとえば、時々、約6か月後のフライトの価格を確認したい場合があります。3か月後、1週間前など。ドロップダウンメニューから選択することで、ユーザーがJSONペイロードをすばやく変更できるUIを提供することはクールです。空港コードなど、他の入力フィールドにも同じものを提供すると、ユーザーが空港コードを検索する必要がなくなります。これにも貴重な時間がかかります。

図5：ペイロードを自動的に調整するためのHTMLフォームの追加

上記のUIにより、JSONペイロードの変更が迅速かつ容易になり、ユーザー側の専門知識はほとんど必要ありません。生成されたJSONを検査することも可能であり、HTMLフォームで対応していないケースをテストしたい場合は、ユーザーが直接変更することもできます。

フライト検索APIは、顧客が最適な出発便と帰国便の組み合わせを選択できる、日付によって異なる価格の行列を返す可能性があります。例として

図6：JSONレスポンスも複雑になる傾向があります。

人間がJSONの価格行列を理解するのは困難であるため、JSONを解析して適切なHTMLテーブルでフォーマットできます。

図7：レスポンスを解析して、読みやすい形式で表示する。

シンプルなHTMLテーブルは、技術的なユーザーと技術的ではないユーザーの両方がAPIの結果を簡単に確認できるようにするための大きな助けとなります。

よくある質問

Swagger UIの代わりに使用しないのはなぜですか？

Swagger UIは、デモフロントエンドと同じいくつかの優れた品質を満たしています。すぐに利用可能になり、ソースコードと同じソースコードリポジトリで定義され、APIを提供するサービスと同じサービスから提供されます。デモフロントエンドと比較して、いくつかの欠点があります。

• Swagger UIの入力と出力のペイロードはJSONに限定されています。読みやすくすることはできません。
• 技術に詳しくないユーザーには使いにくいものです。
• 静的なペイロードしか提供できません。毎回ランダムなIDを提供する必要がある場合、ペイロードに現在の日付を含める必要がある場合どうでしょうか？ユーザーは手動でペイロードを修正する方法を覚えておく必要があり、修正方法を知る必要があります。少しのJavaScriptを使用すると、デモフロントエンドで簡単に自動的に提供できます。
• Swagger UIはワークフローをサポートしていません。デモフロントエンドを使用すると、実行する呼び出しを適切な順序で提示することでユーザーをガイドできます。また、1つの呼び出しの出力から一部を取り出し、それらを使用してワークフロー内の次の呼び出しのペイロードを準備することもできます。

`npm`で専用のビルドを設定する必要がありますか？

フロントエンドで専用のビルドコマンドを使用している場合、ローカルの編集-コンパイル-実行-テストループに余分な手順があります。これにより、ループが遅くなります。また、継続的インテグレーションとデリバリーの自動化を複雑にする必要もあります。ソースコードリポジトリは1つの代わりに2つのアーティファクトを作成するようになり、両方を作成して展開する必要があります。これらの理由から、お勧めしません。Angularなどの「大規模な」フロントエンドフレームワークに慣れている場合、インライン`<script>`タグに`jQuery`または`React`をロードするだけでどれだけ多くのことができるかに驚くかもしれません。

クライアントが要求していない作業を行っているのではないでしょうか？

デモフロントエンドは、クライアントが評価する可能性のある製品のいくつかのクロスファンクショナルな特性を向上させます。少なくとも、製品のテスト容易性と開発者のエクスペリエンス、つまり開発速度ですが、有益な影響を受ける可能性のある他のクロスファンクショナルな特性もあります。

お話しましょう。少し前に、API製品の書き直しに取り組んでいました。その製品では、API呼び出しによって、他のダウンストリームサービスへの数十回の呼び出しが発生する可能性があり、それらのダウンストリーム呼び出しはそれぞれ、HTTPエラーステータスコードを返すことによるHTTPレベルでの失敗、およびレスポンスペイロード内の論理エラーコードを返すことによる論理レベルでの失敗のいずれも発生する可能性がありました。これらの数十のダウンストリーム呼び出しのいずれかが異なる方法で失敗すると、APIレスポンスに異なる予期せぬ結果が生じる可能性があったため、システムがダウンストリームサービスとやり取りした際に何が起こったかを迅速に確認する方法が必要であることは明らかでした。そこで、デモフロントエンドを強化し、APIへの1回の呼び出しに対する応答として、各ダウンストリーム呼び出しのリクエストとレスポンスを示す、すべてのダウンストリームサービスのやり取りのレポートを表示するようにしました。

デモフロントエンドは最終的に、テスターが呼び出しが期待通りの結果を生成しなかった理由を簡単にデバッグできるようにしたため、製品の成功に大きく貢献する重要な機能となりました。デモフロントエンドは最終的に本番環境でも利用可能になり、内部ユーザーは製品クライアント（つまり、パートナー）からの呼び出しのトラブルシューティングを行うことができるようになりました。クライアントは、以前のシステムでは数日かかっていたものが、今では数分で呼び出しが期待通りに動作しなかった理由をトラブルシューティングできるようになったため、満足していると伝えてくれました。

クライアントはデモフロントエンドを明示的に要求したわけではありませんでしたが、プロジェクトの開始時に、現在のシステムを使用して、APIへのいくつかの呼び出しが予期せぬ値を返している理由をトラブルシューティングするのがいかに困難であるかを私たちに伝えていました。私たちが彼ら向けに構築したデモフロントエンドは、とりわけ、彼らが私たちに話してくれた問題に対する解決策でした。

さらに詳しく

APIエンドポイントは、ある種の自動化されたワークフロー、または人間のユーザーによる意思決定プロセスをサポートするために、連続して使用されることがよくあります。これらの場合、ワークフローを明示的にサポートするためにデモフロントエンドを拡張することがあります。ある意味、デモフロントエンドは、APIユーザーがAPIを使用する方法に関するドキュメント、または完全な実装の例として採用されるプロトタイプフロントエンドとして使用できます。

出発点として使用できるサンプルコードが、このgitリポジトリにあります。スクリーンショットはここから取得しました。