単独行動からの解放: Postman と API 開発で共同作業する方法を学ぶ

API 開発は、私がソフトウェアで好きなことの大きな部分を占めています。統合を構築する場合でも、分離された Web アプリケーション用の API を作成する場合でも、通常は私とコードだけで作業します。

ほとんどの場合、私は単独の API 開発者として働いています。ソロ活動には、迅速な意思決定と完全なコントロールという利点があります。しかし、すべてを頭の中に入れておくと引き継ぎや委任が難しくなるため、これは諸刃の剣でもあります。そして、ソロで活動すると、私が取り組めるプロジェクトの規模と複雑さが制限されます。結局のところ、私はただの一人の人間です。

Postman は、リクエストの送信、環境の管理、テストの実行といった API 作業のための私の主要なツールです。私はソロのワークフローに慣れています。しかし、私は疑問に思い始めました。チーム環境において、Postman はこれ以上何を提供できるのでしょうか?どのようにコラボレーションを強化し、開発プロセスを合理化できるでしょうか?

これらの疑問を探るために、私は「X Nihilo」と呼ぶサンプル API の開発に取り組み始めました。

API の例: X Nihilo

X Nihilo は、保存または送信したパラメーターに基づいて 280 文字のツイートを生成するのに役立ちます。トピック、目標、取り上げるトーンの説明、および聴衆の説明を提供します。 API は舞台裏でテキスト補完のリクエストを OpenAI の API に送信し、ツイートの生成を支援します。

さらに、トーンと視聴者に使用する文字列を保存し、後続のツイート リクエストで再利用できます。

基本的な API 開発ワークフローを見てみましょう。

一人で取り組む: 私のソロワークフロー

私のワークフローの最初のステップは、API を設計し、OpenAPI 仕様を作成することです。 Postman で、新しい API を作成し、新しい API 定義を開始しました。

いくつか考えた後 (そして ChatGPT を直接操作したため、説明に基づいて初期の OpenAPI 仕様を生成するのに最適でした)、仕様を作成しました。

OpenAPI 仕様を整えたところで、私は分かれ道に差し掛かりました。この API との対話がどのようになるかを示すために、モック サーバーといくつかのリクエストと応答のサンプルをセットアップする必要がありますか?それとも実装コードを書き始めるべきでしょうか?

個人の開発者として、私は常に API プロデューサーまたは API コンシューマーにしかなれません。そこで私は、モックを作成する必要はない、私の中の消費者は待つ必要がある、と決めました。コードを書いてみましょう!

数分後…

Express で Node.js を使用し、PostgreSQL データベースと通信して、基本的な API を実装しました。構築するために必要なものの概要は次のとおりです。

• POST /signin usernameとpasswordを取得し、データベース内のレコードに対して認証して、後続のすべてのリクエストで使用できる署名付き JWT を返します。
• POST /generateTweet 280 文字 (最大) のツイートを生成します。 topic (文字列) とgoal (文字列) を必要とします。また、 tone (文字列) またはtoneId (保存されたトーンの整数 ID) のいずれか、およびaudience (文字列) またはaudienceId (保存されたオーディエンスの整数 ID) も受け取ります。 toneやaudience文字列が提供されるたびに、API はこれらをデータベースに保存します。
• GET /tonesトーン ID と対応する文字列のリストを返します。 GET /audiences再利用可能なオーディエンス文字列に対して同じことを行います。
• DELETE /tonesトーン ID を取得し、そのトーン レコードを削除します。 DELETE /audiences視聴者レコードに対しても同じことを行います。

最初の実装が完了したら、Postman に戻っていくつかのリクエストの実行を開始します。

変数を使用して環境を作成します。

まず、「Test」という新しい環境を作成しました。 root_url有効なusernameとpasswordとともに保存するための変数を追加しました。

コレクションとリクエストを作成する

次に、新しいコレクションを作成し、最初のリクエストであるPOSTリクエストを/signinに追加して、認証を試しました。

ターミナル ウィンドウで API サーバーを実行し、最初のリクエストを送信しました。

成功！トークンを取得しました。今後のリクエストで必要になります。

今回はツイートを生成するために、新しいリクエストを作成しました。

「ベアラー トークン」を使用するように認証を設定し、前のリクエストで受け取ったばかりのトークンを指定しました。

応答は次のとおりです。

それは動作します！

ソロアプローチをまとめると

以上が私のソロワークフローの基本的な概要です。もちろん、途中で他にもいくつかのことを行います。

• /signin要求を実行する事前要求スクリプトを作成し、応答内のトークンに基づいて環境変数を設定します。
• OpenAPI 仕様の他のすべてのエンドポイントに対するリクエストを作成します。
• 各エンドポイントのテストを作成し、エッジ ケースを確実にカバーします。

一人で作業している場合は、この基本的なワークフローでゴールラインにかなり近づくことができます。それは問題ありませんが、おそらく Postman で利用できる機能の表面をなぞっただけであることは承知しています。そして、チームで作業している場合は、Postman からさらに多くのことを必要とすることもわかっています。

なるほどと思う瞬間: なぜチームに Postman を検討するのでしょうか?

X Nihilo の単独 API 開発者になれなくなったらどうしますか?これはいくつかの理由で発生する可能性があります。

• X Nihilo はサイズと複雑さが増大し、1 人の API 開発者ではサポートできなくなりました。
• X Nihilo は、複数の API 開発者、場合によっては複数の API チームが関与する大規模な API プロジェクトのほんの一部にすぎません。

クライアント向けの API プロジェクトのすべてが、自分で構築できる小規模なプロジェクトであるとは限りません。場合によっては、API を構築するチームの一員になる必要があります。 API チームをリードする必要があるかもしれません。

そうなると、ソロの考え方を捨てて、ソロで物事を進める方法を Postman に残す必要があります。これが私に Postman のチーム関連の機能を調べてみようという動機を与えました。

Postman のチーム (エンタープライズ) 機能の探索

Postman には無料枠があり、いくつかの限定的なコラボレーション機能が提供されますが、小規模なチーム (開発者が 3 名以下) の場合はこれで十分かもしれません。 Postman には、Enterprise Essentials 層の一部として追加機能があります。これらは、Postman を全面的に使用する大規模な組織の API チームに最適です。

ワークスペースの共有

ワークスペースを使用すると、チームは複数の API プロジェクトで共同作業できます。これは、さまざまなチームがさまざまな API に取り組んでいるが、それらの API が相互にやり取りする場合に最適です (これは通常、大規模なソフトウェア組織の場合に当てはまります)。

ワークスペースは、リアルタイムのコラボレーションを可能にするのに優れています。チームメンバーは、API ドキュメントを編集し、リクエストの作成やテストの作成で共同作業し、チーム全体が使用できる模擬サーバーを構築できます。編集が行われると、編集内容はリアルタイムでチーム全体と同期されます。

バージョン管理

私は単独の API 開発者として、コードのバージョン管理については気にしていましたが、Postman コレクションや環境のバージョン管理についてはあまり気にしていませんでした。私が何かを変更した場合 (リクエストの変更、テストの更新、環境変数の削除)、影響を受けるのは私だけです。大きな問題ではない。

チームで働くときは、状況がいつ変化するかを必ず知りたいと思うでしょう。また、変更をロールバックする必要がある場合もあります。幸いなことに、Postman Enterprise を使用しているチームの場合、 Postman を使用すると、コレクション、ワークスペース、API の変更ログにアクセスできます。コレクションを以前の時点にロールバックできます。チームの API 開発者として、これが必要になります。ほとんどの場合、それはボブがコレクションを台無しにしたためです。でも時々、あなたはボブです。

役割ベースのアクセスとユーザー組織

Postman ワークスペース内の全員が同じレベルの権限を持つ必要があるわけではありません。チーム メンバーの一部はテスターであり、要求を送信してテストを実行する機能のみが必要ですが、変更は必要ありません。他の人は、API 定義の変更のみを許可されている設計者である可能性があります。

Postman では、チーム メンバーに役割を割り当てることができます。これは、チームまたはワークスペース内で各チーム メンバーが持つアクセスの種類と権限のレベルに影響します。

チームはプライベート ワークスペースを持つこともでき、チーム外のユーザーからのアクセスを制限できます。

Postman Enterprise が「ドメイン キャプチャ」をサポートしていることにも気付きました。これは基本的に、(たとえば) mycompany.bizドメインからすべてのユーザーにアクセスを許可することで、組織内のすべてのユーザーを設定できることを意味します。

インラインコメントとディスカッション

Postman には、Enterprise Essentials だけでなく、すべてのプランで利用できるコラボレーション機能が 1 つあります。これは、チーム メンバーがコレクション (フォルダー、リクエスト、サンプル、またはプル リクエスト) にコメントを追加できる機能です。 Postman で直接コメントしたり議論したりできることは、チーム API 開発にとって非常に役立ちます。チームの API 開発作業のほとんどは Postman で行われるため、(GitHub やその他の外部サービスではなく) Postman でディスカッションを行うことは理にかなっています。

チーム API 開発: Postman の勝利

チームに参加するときは、自分が愛用しているツールを持参しますが、それをチームメイトに押し付けることはありません。彼らは独自のツールを持っていると思います。だから、それぞれ自分のものに。しかし、ほとんどの API 開発者のツールベルトには Postman が組み込まれているように感じます。チーム内の複数の API 開発者が全員、単独の考え方で Postman を個別に使用し、これらのチーム機能の一部を活用しないのは、まったく残念なことです。 Postman Enterprise の機能を活用すると、次のようなメリットが得られます。

効率の向上

共有ワークスペースでは、共有 API 定義から始めることができます。チーム メンバーが定義 (またはドキュメント、テスト、環境) を編集すると、編集内容が同期され、全員が最新かつ最高のものを使用できるようになります。

全員がコレクション内の同じリクエストのセットを処理し、使用されるすべてのテストに全員がアクセスできます。これらすべての利便性によりチームの効率が向上し、開発速度が飛躍的に向上します。

誤解の減少

全員が同じ情報源 (ワークスペース) に基づいて作業し、開発に使用しているツール内でコメントしたり会話したりできると、誤解が少なくなります。チームは、そのエンドポイントがクエリ パラメーターとパス パラメーターのどちらを取ることになっていたかについて混乱するために時間を無駄にすることはありません。すべてが明らかになるでしょう。

重要なポイント

Postman がチームや企業向けであるとは知りませんでした。さて、ここで私の重要な教訓をお伝えします。チーム プレーヤーはチームにとって有益なツールを使用します。

Postman は、私が単独の API 開発者である場合に非常に役立ちました。幸いなことに、API 開発チームに所属しているときに便利になる機能も備えています。私にとって、それはコレクション内の編集内容、変更ログ、バージョン管理のリアルタイム同期、およびアクセスに対する詳細な権限です。今では、大規模なチームで大規模な API プロジェクトに取り組むことに興奮しています。

コーディングを楽しんでください!

ここでも公開されています。