この記事では、効率的な API 設計、テスト、コラボレーションのために設計された API ファーストツールである Apidog の中核概念を紹介します。多くの概念は、Postman のような類似製品とは異なります。これらを理解することで、Apidog のワークフローを効果的に進められるようになります。プロジェクト#
Apidog における プロジェクト は、コラボレーションの主要な単位であり、モジュール、環境、テストシナリオなどを含みます。チーム内のすべての API 関連作業を格 納するコンテナとして機能します。プロジェクトの主要コンポーネント#
モジュール: エンドポイントおよび関連コンポーネントの論理的なグループです。
環境: さまざまなデプロイ段階（例: 開発、ステージング、本番）向けの変数セットです。
テストシナリオ: 自動テスト用のリクエストのコレクションです。
エンドポイント仕様: OpenAPI/Swagger 標準に基づく API ドキュメントです。
Postman との比較#
| Apidog の概念 | Postman での相当概念 | 説明 |
|---|
| プロジェクト | ワークスペース | コラボレーションのための最上位の組織単位です。 |
| モジュール | コレクションフォルダー | 関連するエンドポイントをグループ化します。 |
| チーム | チーム | 共有アクセスおよびコラボレーション機能です。 |
プロジェクトにより、複数のユーザーがバージョン管理とアクセス権限を維持しながら、API に対して同時に作業できるため、シームレスなコラボレーションが可能になります。
モジュール#
Apidog の モジュール は、プロジェクト内でエンドポイントを論理的に整理するもので、マイクロサービスアーキテクチャにおける「サービス」に似ています。各モジュールは、独立した OpenAPI 仕様ファイルを表します。モジュールの機能#
関連するエンドポイント、スキーマ、レスポンス、セキュリティスキームを含みます。
自動 URL 生成のために、環境ごとに Base URL を設定します。
標準への準拠性を高めるため、モジュールレベルでのインポート/エクスポート操作をサポートします。
モジュールを使用する場合#
マイクロサービスの場合: 各サービスを個別のモジュールとして扱います。
複数の API の場合: 機能またはドメインごとにエンドポイントをグループ化します。
デフォルト: 新しいプロジェクトは 1 つのモジュールから開始されます。複数のベース URL が必要な場合は、必要に応じて追加します。
モジュールは OpenAPI Specification（OAS）に準拠しており、他のツールとの統合を容易にし、明確な API 境界を維持します。
エンドポイント#
エンドポイント は、Apidog の API ファーストアプローチにおける中核要素であり、特定の API 操作（例: GET /users/{id}）を表します。エンドポイント管理#
整理のためにディレクトリ構造内でグループ化されます。
保存済みリクエスト例のために エンドポイントケース と関連付けられます。
Postman との違い#
| 観点 | Apidog（エンドポイントベース） | Postman（リクエストベース） |
|---|
| 基本単位 | エンドポイント（API 仕様） | リクエスト（個別の呼び出し） |
| 仕様変更 | ケースとテストを自動更新 | 手動での書き直しが必要 |
| 構造 | デバッグを備えた OAS 拡張 | 仕様とリクエストが分離 |
Apidog では、エンドポイント仕様への変更が依存するすべてのケースに自動的に反映されます。この仕様駆動型アプローチにより、メンテナンスの負担が軽減されます。
主な機能#
自動 URL 構築: Base URL + Endpoint Path。
Base URL の例#
| サービス | Base URL（本番） | エンドポイントパス | 完全な URL |
|---|
| User | https://user.example.com | GET /user/{id} | https://user.example.com/user/{id} |
| Order | https://order.example.com | GET /order/{id} | https://order.example.com/order/{id} |
| Product | https://product.example.com | GET /product/{id} | https://product.example.com/product/{id} |
手動で {{BaseUrl}} プレースホルダーを使用する必要はありません。Apidog はモジュールを検出し、正しいベース URL を自動的に適用します。
リクエスト#
リクエスト は、エンドポイント仕様に関連付けられていない単独の API 呼び出しであり、Postman のリクエストに似ています。リクエスト機能#
成功したリクエストをエンドポイント仕様に解析できます。 アドホックなテストや、ドキュメント化されていない API に使用します。
リクエストは、API 仕様が事前に定義されていないシナリオに柔軟性を提供し、設計ファーストとリクエストファーストのワークフローの間を橋渡しします。
テストシナリオ#
テストシナリオ は、Postman Collections に似たリクエストのバッチを実行し、高度な自動化機能を備えています。高度な機能#
テストシナリオは API 仕様の変更と自動同期されるため、API が進化してもテストの有効性が維持されます。
Design-first Mode と Request-first Mode#
Apidog の API モジュールには、インターフェース左下隅で切り替え可能な 2 つのモードがあります: Design-first Mode と Request-first Mode です。どちらのモードも類似した機能を提供しますが、インターフェースが異なり、さまざまなチームのワークフローに対応します。Design-first Mode#
Request-first Mode#
バックエンド開発を先に重視するチームに適しています。
リクエストを作成し、成功した呼び出しから仕様を生成します。
ドキュメント化されていない API やサードパーティ連携に最適です。
まとめ#
これらの中核概念を理解することで、効率的な設計、テスト、コラボレーションのために Apidog の API ファーストアプローチを活用できるようになります。まずプロジェクトを作成し、エンドポイントをモジュールに整理し、さまざまな段階向けの環境を定義し、自動化のためのテストシナリオを構築してください。さらに詳しくは、リンク先のドキュメントページを参照するか、Apidog のインターフェースを試して、これらの概念が実際にどのように機能するかを確認してください。
開始する準備はできましたか？#
Apidog へ移行
Apidog への移行から開始する 