API製品仕様としてのプロトタイプの使用

SendGridのデベロッパーエクスペリエンスプロダクトマネージャーとして、APIに関連する機会、機能、製品を特定する任務を負っています。 私が取り組んできた1つのことは、自分の製品のアイデアを他のPM、エンジニア、および顧客にさらに効果的に伝達する方法を特定することです。

モノリシック製品要件ドキュメント（PRD）はこれを行うための理想的な方法ではなく、製品仕様と同じ情報を含むテスト可能なインターフェイスが強力な代替手段になることを学びました。 PRDの問題は、PRDが非常に大きく、ほとんどがテキストであることが多いことです。 あなたの場所を失ったり、本当に重要な何かを見逃したりするのは簡単すぎます。

UXの私たちの友人は、 Invisionのようなツールを使用してこの問題を解決しました。このツールでは、インターフェイスを説明するだけのドキュメントやワイヤーフレームではなく、タッチして使用できるクリック可能なインターフェイスが提供されます。 APIはインターフェースであるため、ドキュメント内の一連の説明テキストやJSONではなく、仕様とリアルタイムで対話できるツールが必要です。

要件の定義

製品仕様としてのこのテスト可能なインターフェースはどのように見えるべきですか？ それはどのように機能しますか？ それは存在しますか？

Marty CaganのInspired：How to Build Products Customers Loveの第18章「製品仕様の再発明」を読んでいたとき、私は、製品仕様に関するCaganの要件を満たす、使用しているツールを共有したいと思いました。彼の製品仕様のウィッシュリスト、および仕様としてのプロトタイプ要件の私自身の個人的なリスト。

Caganの要件*：

• 仕様では、完全なユーザーエクスペリエンスを説明する必要があります。
• 仕様は、ソフトウェアの動作を正確に表す必要があります。
• すべての利害関係者が必要なものを入手できるように、製品を伝達できる必要があります。
• スペックが変更されます
• あいまいさやバージョン炎を減らすために、仕様の単一のマスター表現が必要です。

Caganのウィッシュリスト*：

• プロトタイプを補足する必要があります[で]：
  • ビジネスの論理
  • リリース要件
  • プラットフォームの配信要件
  • ユースケース
• プロトタイプに注釈を付けられるようにしたい

仕様としてのプロトタイプの私の要件：

• プロトタイプは仕様である必要があります。
• ドキュメントはプロトタイプに統合する必要があります。
• それを必要とする会社の誰もがプロトタイプとドキュメントにアクセスできる必要があります。
• 顧客は、ユーザーテストのためにプロトタイプの機能部分にアクセスできる必要があります。
• プロトタイプは仕様を置き換え、完成品を配線することなく、意図した機能にできるだけ近く機能する必要があります。
• プロトタイプに変更を加えて記録するのは簡単なはずです。
• プロトタイプにアクセスできる人なら誰でもテストできるA/Bバリエーションを簡単に作成できるはずです。
• プロトタイプから顧客のドキュメントを簡単にエクスポートできるはずです。

StopLightの紹介

上記のほぼすべてを満たす私が使用しているツールは、 Stoplight.ioと呼ばれます。 これは、APIドキュメントエンジンとWebプロキシの中核です。 直感的なUIを使用してAPIを定義できます。このUIは、仕様エンジンとしてSwaggerとRAMLの両方の長所を備えており、どちらの形式からもインポートまたはエクスポートできます。

StopLightはドキュメントツールであるため、エンドポイントのリクエスト、レスポンス、ヘッダー、説明を定義できます。 プロキシ機能を使用すると、APIを呼び出して、呼び出しが仕様に一致することを確認したり、エンドポイントを自動検出して、ほとんどのドキュメントを自動的に作成したりできます。

StopLightのプロキシには、他にもいくつかの非常にすばらしい機能があります。

• 製品が完成していない場合、またはリクエストをプロキシしたくない場合に、エンドポイントに模擬通話を発信する機能。
• マシンでプロトタイプをテストするためのローカルサーバー。
• インターネット上でプロトタイプをテストするためのリモートサーバー。
• プロトタイプのエンドポイントが呼び出される前および/または後に実行できるコードを定義するための、Javascriptで記述されたミドルウェア。

私のウィッシュリスト、Caganの仕様要件、および彼のウィッシュリストの組み合わせを、StopLightが提供する機能と比較すると、StopLightがすべてのニーズと要望を満たしていることがわかります。

• プロトタイプとその機能の内部のみのドキュメント。
• 機能の簡単にアクセスできる完全なプロトタイプ。
• ユーザーのテストとフィードバックのために可変機能を切り替える機能を備えたテスト可能なインターフェース。
• 特定の会話用にプロトタイプをバージョン管理する簡単な方法。これにより、プロトタイプの機能をほぼリアルタイムで変更して、受け取ったフィードバックを説明および検証できます。

StopLightのワークフローはシンプルで、技術的な能力に関係なく、誰でも実行できます。

• 新しいプロジェクトを作成します。
• エンドポイント、そのパラメーター、要求、および応答に関する情報をクリックして入力することにより、仕様を追加します。
• 定義画面でプロトタイプに関する仕様情報を追加します。
• オプション機能がある場合は、ミドルウェアを使用してそれらを追加します。
• モックをオンにします。
• モッキングサーバーのパブリックURLをコピーして貼り付け、フィードバックのために共有します。

顧客訪問を行っていて、プロトタイプをリアルタイムで実験したい場合は、定義をコンピューターにダウンロードし、訪問にちなんで名付けられた新しいプロジェクトを作成して、定義をインポートします。 これで、元のプロトタイプを変更せずに、必要なものを変更できます。 戻ってアイデアをマージするときは、最初にプロトタイプを作成するのと同じくらい簡単に変更を加えることができます。

開発者エクスペリエンスのプロダクトマネージャーであるStopLightは、仕事をより効率的に行うのに役立つだけでなく、使い方が非常に簡単で、顧客の検証手順の前にドキュメントが開始されて更新されるため、APIをドキュメント化する配信準備手順が簡単になります。プロセス全体を通して。 StopLightが提供する他の多くのユースケースと機能がありますが、これは私の仕事に最も大きな影響を与えたものかもしれません。

* Caganの要件とウィッシュリストは、 Inspired：How to Build ProductsCustomersLoveからの直接の引用です。