Apidogでは、APIの設計と設定は堅牢で効果的なAPIを作成するための基本的なステップだ。OpenAPIエコシステム内の様々なツールやサービスとの互換性を確保するため、OpenAPI仕様(OAS)に準拠してAPIを設計することを推奨する。OASから逸脱すると、OpenAPI準拠のツールやサービスを使用する際に互換性の問題が発生する可能性がある。API
モジュール内で新しいAPIを作成するには、新しいAPI
ボタンをクリックする。明確で完全なAPIには以下の要素が含まれるべきだ:ApidogのAPIインターフェースには、「設計優先」と「リクエスト優先」の2つのモードがあります。「設計優先」はAPI設計を優先し、「リクエスト優先」はコードを優先するアプローチです。インターフェースの左下隅でモードを切り替えることができます。設計優先/リクエスト優先について詳しく学ぶ。 APIパス#
APIパスは、APIが外部アプリケーションと対話できる特定のアドレスとして機能する。クライアントがAPIサービスにアクセスする際に使用する。APIパスは明確な階層構造を持ち、リソース間の関係を明確に表現できるべきだ。設計過程では、APIの拡張性と理解のしやすさも考慮する必要がある。パスボックスでスラッシュ/で始まるAPIパス部分(例:/pets
、/pets/{id}
)。APIパスにはクエリパラメータ(URLの ?
以降のパラメータ)を含めるべきではない。代わりに、これらは下のリクエストパラメータセクションで指定する。パスを/で始めることは、OASに準拠するために推奨される。パスを/で始めないと、OpenAPIエコシステム内のツールを使用する際に様々な互換性の問題が発生する可能性がある
また、パスの先頭に/を使用することで、Apidogでテストと検証に不可欠なURLパターンモック機能を利用できる
リクエストメソッド#
リクエストメソッドは、クライアントがサーバーサイドのリソースとどのように対話するかを決定する。各メソッドは独自のセマンティクスを持ち、サーバーのレスポンスを指示する。APIを設計する際は、意図した操作を効果的に実行するために、ビジネス要件に基づいて最適なリクエストメソッドを選択する。一般的に使用されるAPIリクエストメソッドは以下の通り:1.
GET: 副作用なく指定されたリソースを取得。クエリパラメータを使用してデータを送信
2.
POST: 処理用のデータを送信し、副作用がある可能性がある。通常データはリクエストボディで送信
3.
PUT: 指定されたリソースを完全に更新または置換
5.
OPTIONS: 対象リソースがサポートするHTTPメソッドを問い合わせ
6.
HEAD: GETと似ているが、レスポンスヘッダーのみを取得。リソースコンテンツをダウンロードせずにリソースの存在と変更を確認するのに有用
7.
PATCH: 指定されたリソースの部分的な情報を更新
8.
TRACE: サーバーが受信したリクエストを返す。主にデバッグと診断目的で使用
9.
CONNECT: サーバーへのトンネルを 確立。通常、プロキシサーバーのリクエスト転送に使用
APIメタデータ#
Apidogでは、APIにはデフォルトのメタデータフィールドが付属しており、APIのドキュメント、アクセシビリティ、ライフサイクルを定義・管理する。ステータス
デフォルトのステータスは「開発中」。「APIステータス」で開発、テスト、本番などの異なる段階を反映するように変更できる
担当者
APIを担当するApidogチームメンバーを指定。アカウントからユーザーを選択して役割を割り当てる
タグ
APIを分類または説明するキーワードやフレーズ。入力して新しいタグを作成するか、既存のタグから選択できる
サービス
APIパスが追加されるベースURL。デフォルトでは「親から継承」に設定されているが、インターフェース右上の環境設定で手動で指定可能
オペレーションID (operationId)
API内でこの操作を区別するための一意の識別子(OASのoperationId)
説明
APIの目的と使用方法に関する詳細情報。拡張フォーマット用にMarkdownをサポート
リクエスト#
リクエストパラメータ#
リクエストパラメータは、データの返却を制御したり、サーバーのレスポンスを変更したりするためにリクエストと共に渡すことができるオプションだ。リクエストパラメータには、クエリパラメータ、パスパラメータ、ヘッダーパラメータ、ボディパラメータがある。Queryパラメータ#
クエリパラメータは、URLの末尾に疑問符 '?'
の後に追加され、&
で区切られるキーと値のペアで、以下のような形式になる: ?id=2&status=available
。APIの出力をフィルタリング、ソート、または変更するために使用される。Apidogでは、明確さと整理のためにクエリパラメータは別のセクションで記述される。ただし、リクエスト送信時には、これらのクエリパラメータは上記の方法でAPIパスと連結される。
Pathパラメータ#
パスパラメータはAPI URLの一部であり、API内の特定のリソースやエンティティを識別するために使用される。Apidogでは、パスパラメータはコロンではなく中括弧で示される。正しい例: /pets/{id}
、誤った例: /pets/:id
。パスパラメータを追加するには、APIパスに{ パラメータ
}を追加するだけで、パラメータは自動的に「 パスパラメータ
」領域に表示される。{パラメータ
}:単一の中括弧は、Apidogでパスパラメータを表すために使用される。パスパラメータはAPIにアクセスする際に特定の値に動的に変化するURLパスのプレースホルダーだ。
{{変数
}}:二重の中括弧は、Apidogで リクエスト内に変数を含めるために使用される。これらの変数は、リクエスト送信時に実際の値で置き換えることができ、API連携での動的でカスタマイズ可能な入力を可能にする。
パスで{{
変数
}}を使用することが推奨されない理由
{{変数
}}を使用することはOASに準拠していない。OASに従うことで、OpenAPIエコシステム内の様々なツールとシームレスに統合できる。
パスで{{変数
}}を使用すると、ApidogのURLパターンモック機能が使用できなくなる。
ヘッダーパラメータ#
ヘッダーパラメータは、リクエストに関する追加情報を提供し、通常、認証、コンテンツタイプ、その他のメタデータに使用される。