シェア:
){kind=small}
ディンピーはVonageのスタッフ・クオリティ・アーキテクトで、オートメーションとパフォーマンス・エンジニアリングを専門としています。20年近く品質エンジニアリングに携わってきた彼女は、情熱的な品質擁護者でありソート・リーダーとして、強固なテスト戦略を推進し、シフト・レフトの実践を支持している。カンファレンス、ミートアップ、メンターシップを通じて知識と洞察を共有し、テストコミュニティに還元することに大きなやりがいを感じている。
APIコレクションで開発者をオンボーディングする
所要時間：1 分
この投稿では、Postman、Bruno、Insomniaのようなツールで作成されたAPIコレクションを使ってAPIを設計する製品思考のアプローチが、どのようにオンボーディングの成果物として非常に効果的であるかを説明する。
これらのコレクションは、開発者が実世界のデータを使ってワークフローを試し、摩擦を減らし、より早く生産的になるのを助けるインタラクティブなガイドです。単なるリクエストビルダーではありません。
OpenAPI仕様の価値は高いが、実際の採用を促進する上で失敗しがちな理由を検証する。また、コレクションがどのようにAPIのストーリーを伝え、バージョン管理されたコードベースと一貫性を保ち、ユーザビリティと反復の文化を可能にするかについても議論します。
フォローするには、以下のものが必要だ：
Postman、Bruno、Insomniaのようなツール（例ではPostmanを使用）
Vonage APIキーまたはテスト環境へのアクセス
基本的なAPIの概念に精通していること
APIコレクションとは、あらかじめ定義されたリクエストのセットで、APIをどのように扱うかを、整理された例主導の方法で示したものである。通常、Postman、Bruno、Insomniaなどのツールで使用されるが、構造化されたcURLスクリプトを使用して作成することもできる。
コレクションが特に強力なのは、その双方向性です。開発者はエンドポイントについて読む代わりに、それを実行し、パラメータを変更し、リアルタイムでレスポンスを観察することができます。
リクエスト定義（メソッド、URL、ヘッダー、ボディ）
環境変数（認証トークンやベースURLなど）
ワークフローを表すフォルダ構造（例、 認証、ユーザー作成、メッセージ送信)
インライン・ドキュメント
検証用テストスクリプト
OpenAPI仕様書は、ツールや検証、自動生成されるドキュメンテーションのために素晴らしいものだ。しかし、それらはまだ設計図であり、実際の建物ではない。何がそこにあるのかを定義しているのであって、いつ、どのように使うのかを定義しているわけではない。順序や物語、文脈もない。
テストSMSを送信 "しようとしているだけの開発者は、レート制限やまだ必要でないオプションフィールドについて深く掘り下げることに没頭してしまうかもしれません。良い例がなければ、開発者は当て推量に頼ることになる：
このヘッダーは必要ですか？
このURLパラメータはエンコードすべきでしょうか？
トークンは有効なのに、なぜ401が表示されるのですか？
コレクションは、開発者やユーザーが意図しない動作のトリガーを心配することなくワークフローをテストできる、構造化された編集可能な環境を提供します。
APIコレクションは、社内外を問わず、目に見える形でデベロッパーエクスペリエンスを向上させます。
APIコレクションは、空白ページの問題を解消します。ゼロから始めるのではなく、開発者はコレクションを開いて即座に確認することができる：
プリフィルド・リクエスト
管理される認証変数
頻繁に使用されるケースのための明確な構造
これにより、開発者は素早く成功を収め、早期に勢いをつけることができる。
APIコレクションは、静的なドキュメントにはできない方法で、探索をサポートする。APIコレクションは、例えば、learn by doingマインドセットを奨励することができる：
このパラメータを変更するとどうなりますか？
これらの通話を組み合わせることはできますか？
エラー処理はどのように行われるのか？
コレクションは、チーム全体で共有される言語として機能する：
開発者は失敗したリクエストをエクスポートできる
サポートエンジニアは問題を再生し、切り分けることができる
QAチームはステージングでフローを検証できる
環境変数を使えば、コレクションを簡単に横断的にテストできる：
ローカル開発セットアップ
ステージングまたはサンドボックスAPI
本番環境（慎重に）
APIコレクションは、自動テストやコードレビュー中の受け入れ基準の検証で使用できる。
コレクションは、異なるチームがAPIの動作について足並みを揃えるのを助ける。製品と共に進化する生きたドキュメントとして機能する。
コレクションは、送受信されたものを正確に表示します。この可視性により、信頼性が高まります -8 特に、透明性が重要な企業や規制環境では。
以下のサブセクションでは、効果的なAPIコレクションを構築するためのステップバイステップのアプローチを見つけることができます。
OpenAPI仕様をPostmanにインポートするだけではいけません。実際のワークフローから始めましょう：
最も一般的な開発者の行動は何ですか？
APIの "Hello, World "とは？
充実した旅とはどのようなものだろうか？
例えば、こうだ：
テストユーザーの作成 → ログインのシミュレーション → トークンの生成
SMSを送信する → メッセージのステータスを取得する
Postman、Bruno、Insomnia、あるいはVS Code REST Clientなど、チームのワークフローに合ったツールを選ぼう。
プロジェクト/ワークスペースを作成し、追加する：
新しいコレクション（例． 顧客オンボーディングAPI)
論理的なグループ分けのためのフォルダ（認証、ユーザー、支払い）
とのリクエスト：
説明的な名前 (作成ユーザー, トークンの取得)有効なデフォルトパラメータ
短いインライン説明
ハードコードされた値を変数に置き換える： {{api_key}}, {{base_url}}そして {{access_token}}.
そのための環境を整える：
地域開発
ステージング
製造
社内で使用する場合は、ワークスペースを通じて環境設定を共有する。
外部ユーザー向けには、値の例とセットアップ手順を含める。
オプション：OAuthフロー用にトークンを自動生成するプレリクエストスクリプトを追加する。
すべてのリクエストに対して：
成功した回答例の追加
一般的なエラー・レスポンス（401、403、500）を含む。
レスポンスを検証し、以降のリクエストで再利用可能な値（トークンやIDなど）を抽出するためのテストスクリプトを書く。
コレクションをコードのように扱う：
GitHubリポジトリに保存する
スプリントレビュー中の更新
リリースノートに沿ったタグまたはブランチを持つバージョン
Public WorkspacesまたはGitHubでコレクションを公開する。
セットアップ手順のREADMEを含める
基本環境テンプレートの提供
GitHubまたは共有ワークスペースに保存する
社内ポータル、Notion、または入社時のドキュメントにピン留めする。
Slackのボットを使ってリンクを表示する。Auth API Collectionを使う → [リンク]"
Vonage Contact Center APIと統合したい場合は、公式のPostmanコレクションを使って統合できます。次のステップでは、オンボーディングフローがどのように見えるかをお見せします。オンボーディングフローはこんな感じです。公式の 公式Vonage Postmanコレクションをご覧ください。
下の画像では、このコレクションのルートレベルのフォルダーを見ることができる：
Root-Level API Folders in Postman Collection
Postmanの公開ページから、Forkをクリックする。
Fork a Postman Collection for Vonage APIs
ワークスペースを作成/選択します（例：customer-support-dev）。
Create Postman workspace from Fork
新しい環境を作る。
Root-Level API Folders in Postman Collectionなどの変数を追加する。 {{client_id}}, {{client_secret}}そして {{region}}.
Vonage Auth Token Request from PostmanPostmanのドロップダウンからこの環境を選択する。
Select Environment in Postman
リクエストを実行する POST auth/connect/tokenリクエストを実行する。
Note: Postmanは前のステップの環境設定を使って変数を自動入力します。
Vonage User API GET Request from Postman
実行 GET /usersを実行します。
Vonage Auth Endpoint Setup in Postmanおめでとう、あなたは認証され、フローをテストする準備ができた。
それも可能だ：
新しいフォルダで拡張する
パラメータの変更
チーム全体で共有する
アプリのコードと一緒にバージョンアップする
自動テストやCI統合でこれを拡張したり、VoiceやMessagesのような他のVonage APIにコレクションを適応させることもできる。
私たちが APIオンボーディング製品体験として APIコレクションは単に便利なだけでなく、戦略的な仲間になる。慎重に作成されたAPIコレクションは以下のことを可能にする：
新規開発者の初期設定と学習曲線を簡素化します。
開発者がAPIを素早く理解し、効果的に活用できるようにする。
APIエコシステムの意図されたユースケースと機能を通して開発者を導く。
API収集を文書化とバージョン管理の実践に統合することで、学習がインタラクティブで、フィードバックが即座に得られる環境を構築することができる。 APIの採用が真にシームレスに感じられる環境を構築できる。
質問や共有したいことがありますか？Vonageコミュニティ VonageコミュニティSlackまたは 開発者向けニュースレターでフォローしてください。 X（旧Twitter）YouTubeチャンネル YouTubeチャンネルビデオチュートリアルを購読する。 LinkedInのVonage開発者ページ開発者が学び、コミュニティとつながるためのスペースです。つながりを維持し、進捗状況を共有し、最新の開発者向けニュース、ヒント、イベントを把握してください！