Apidog Docs
🇯🇵 日本語
  • 🇺🇸 English
  • 🇯🇵 日本語
HomeLearning CenterSupport CenterAPI References
HomeLearning CenterSupport CenterAPI References
Discord Community
Slack Community
X / Twitter
🇯🇵 日本語
  • 🇺🇸 English
  • 🇯🇵 日本語
  1. API設計
  • Apidog学習センター
  • はじめに
    • Apidog紹介
    • Apidog基本操作
      • 概要
      • 新しい APIを作成
      • APIにリクエストを送信
      • アサーションを追加
      • テストシナリオを作成
      • APIドキュメントを共有
      • さらなる探究
      • リクエストを送信してAPIとして保存
    • Apidog基本知識
      • Apidog操作方法
      • Apidogの基本概念
    • 移行
      • 概要
      • 手動インポート
      • 定期インポート
      • インポートオプション
      • データのエクスポート
      • Import from...
        • Postman からインポート
        • OpenAPI(Swagger)仕様のインポート
        • cURLのインポート
        • Markdownのインポート
        • Insomniaからのインポート
        • apiDocからのインポート
        • .harファイルのインポート
        • WSDLのインポート
  • API設計
    • 概要
    • コンポーネント
    • 常用フィールド
    • グローバルパラメータ
    • API変更履歴
    • プロジェクトの作成
    • 一括API管理
    • APIの基本
    • 複数のリクエストボディ例の設定
    • Schemas
      • 概要
      • 新規Schemaの作成
      • スキーマを構築する
      • JSONなどからのSchema生成
    • Security schemes
      • 概要
      • Security Schemeの作成
      • Security Schemeの使用
      • オンラインドキュメントにおけるSecurity Scheme
    • 高度な機能
      • APIをテストステップとしてインポート
      • パラメータリストの表示形式
      • APIのカスタムフィールド
      • APIのステータス
      • API固有識別子
  • API開発とデバッグ
    • 概要
    • リクエストの生成
    • リクエストの送信
    • コード生成機能
    • APIケース
    • 動的な値
    • レスポンスの検証
    • 設計優先 & リクエスト優先
    • 環境 & 変数
      • 概要
      • 環境とサービス
      • 変数の使い方
    • Vault secrets
      • 概要
      • AWS Secrets Manager
      • Azure Key Vault
      • HashiCorp Vault
    • 前/後処理
      • 概要
      • Wait
      • 変数の抽出
      • アサーション
      • データベース操作
        • 概要
        • MongoDB
        • Redis
        • Oracle クライアント
      • スクリプト利用
        • 概要
        • 前処理スクリプト
        • 後処理スクリプト
        • Postmanスクリプトリファレンス
        • 共通スクリプト
        • 他のプログラミング言語の呼び出し
        • JSライブラリの使用
        • レスポンスの可視化
        • スクリプトの例
          • その他の例
          • スクリプトを使用したリクエストメッセージの変更
          • スクリプトでの変数の使用
          • アサーションスクリプト
    • 動的値モジュール
  • APIモック
    • 概要
    • スマートMock
    • カスタムMock
    • Mockの優先順位
    • Mockスクリプト
    • クラウドMock
    • セルフホストランナーMock
    • Mock言語 (ロケール)
  • 自動テスト
    • 概要
    • テストレポート
    • テストシナリオ
      • テストシナリオの作成
      • 他のプロジェクトからAPI/APIケースをインポートする
      • リクエスト間でデータを渡す
      • API/APIケースからのデータ同期
      • フロー制御条件
      • テストシナリオのエクスポート
    • テストシナリオ実行
      • データ駆動型テスト
      • スケジュールタスク
      • テストシナリオを一括実行する
      • 他のプロジェクトのAPIの実行環境を管理する
      • テストシナリオを実行する
    • APIテスト
      • 統合テスト
      • 回帰テスト
      • エンドツーエンド(E2E)テスト
      • パフォーマンステスト
    • Apidog CLI
      • 概要
      • Apidog CLIのインストールと実行
      • Apidog CLI オプション
    • CI/CD
      • 概要
      • Jenkinsとの連携
      • Gitlabとの統合
  • APIドキュメント公開
    • 概要
    • Google AnalyticsとDoc Sitesの連携
    • CORS プロキシ
    • クイック共有
    • 可視性設定
    • ドキュメントURLに値を埋め込む
    • APIドキュメントを表示する
    • フォルダツリー設定
    • API SEO設定
    • カスタムレイアウト
    • ドキュメント検索
    • カスタムドメイン
    • ドキュメントサイトの公開
    • APIバージョン
      • 概要
      • APIバージョンの作成
      • APIバージョンの公開
      • APIバージョンごとにAPIの共有
  • リクエスト送信
    • 概要
    • GraphQL
    • gRPC
    • WebSocket
    • SSEデバッグ
    • SOAP/Webサービス
    • デバッグ用のリクエストプロキシエージェントを使用する
    • Socket.IO
    • リクエスト作成
      • リクエストの基本
      • パラメータとボディ
      • リクエストヘッダー
      • リクエスト設定
      • HTTP/2
      • リクエスト履歴
    • 認証と認可
      • 概要
      • CAとクライアント証明書
      • Apidogがサポートする認可タイプ
      • Digest Auth
      • OAuth 1.0
      • OAuth 2.0
      • Hawk Authentication
      • Kerberos
      • NTLM
      • Akamai EdgeGrid
    • レスポンスとクッキー
      • 概要
      • ApidogのAPIレスポンス
      • Cookieの作成と送信
      • リクエストのデバッグ
      • リクエストをAPIとして保存
  • ブランチ管理
    • 概要
    • 新しいスプリントブランチの作成
    • スプリントブランチの管理
    • ブランチ内でのAPIテスト
    • ブランチでAPIの設計
    • スプリントブランチのマージ
  • Apidog MCP Server
    • 概要
    • Apidogプロジェクト内のAPI仕様をApidog MCPサーバー経由でAIに接続する
    • Apidogが公開したオンラインAPIドキュメントをApidog MCPサーバー経由でAIに接続する
    • Apidog MCPサーバーを介してOpenAPIファイルをAIに接続する
  • ベストプラクティス
    • ガイド:ChatGPT APIのトークンとコスト計算
    • Apidog コラボレーションワークフロー
    • API署名の取り扱い方法
    • Apidogでの認証状態の管理
    • OAuth 2.0で保護されたAPIにアクセスする方法
  • 管理
    • オンボーディングチェックリスト
      • 基本概念
      • Apidogスタートアップガイド
    • チーム管理
      • チーム管理
      • チームメンバーの管理
      • メンバーの役割と権限設定
      • チーム活動
      • チームリソース
        • 一般ランナー
        • チーム変数
        • リクエストプロキシエージェント
        • データベース接続
      • リアルタイムコラボレーション
        • チームコラボレーション
    • プロジェクト管理
      • プロジェクト管理
      • プロジェクトメンバーの管理
      • 通知設定
    • 組織管理
      • シングルサインオン(SSO)
        • 概要
        • Microsoft Entra IDの設定
        • Okta設定
        • 組織のSSOを設定する
        • チームへのグループのマッピング
        • ユーザーアカウントの管理
      • SCIMプロビジョニング
        • SCIMプロビジョニング入門
        • Microsoft Entra ID
        • Okta
      • 組織リソース
        • セルフホストランナー
  • 請求情報
    • 概要
    • プランのアップグレード
    • クレジット
    • クレジットカードが使えない?
    • サブスクリプションの管理
  • アドオン
    • API Hub
    • Apidog IntelliJ IDEA プラグイン
    • リクエストプロキシ
      • Apidogウェブでのリクエストプロキシ
      • 共有ドキュメントでのリクエストプロキシ
      • Apidogクライアントでのリクエストプロキシ
    • ブラウザ拡張機能
      • Microsoft Edge
      • Chrome
  • アカウント & 設定
    • アカウント設定
    • 言語設定
    • データバックアップ
    • ネットワークプロキシ設定
    • ホットキー
    • Apidogの更新
    • OpenAPIアクセストークンの生成
    • アカウント削除
  • 参考資料
    • Swagger拡張機能
    • Socket通信:パケットの分断と結合
    • 用語の説明
    • よくある質問
    • API-デザインファーストアプローチ
    • Apidog OpenAPI/Swagger仕様拡張
    • JSONPath
    • XPath
    • 正規表現
    • JSONスキーマ
    • CSVファイルフォーマット
    • Java環境のインストール
    • ランナーのデプロイ環境
    • ApidogフレーバーMarkdown
  1. API設計

APIの指定

Apidogでは、APIの設計と設定は堅牢で効果的なAPIを作成するための基本的なステップだ。
OpenAPIエコシステム内の様々なツールやサービスとの互換性を確保するため、OpenAPI仕様(OAS)に準拠してAPIを設計することを推奨する。OASから逸脱すると、OpenAPI準拠のツールやサービスを使用する際に互換性の問題が発生する可能性がある。
API モジュール内で新しいAPIを作成するには、新しいAPI ボタンをクリックする。
明確で完全なAPIには以下の要素が含まれるべきだ:
1.
APIパス
2.
リクエストメソッド
3.
APIメタデータ
4.
リクエスト
5.
レスポンスと例
設計優先
リクエスト優先
image.png
ApidogのAPIインターフェースには、「設計優先」と「リクエスト優先」の2つのモードがあります。「設計優先」はAPI設計を優先し、「リクエスト優先」はコードを優先するアプローチです。インターフェースの左下隅でモードを切り替えることができます。設計優先/リクエスト優先について詳しく学ぶ。

APIパス#

APIパスは、APIと外部アプリケーションがやり取りを行うための特定のアドレスであり、クライアントはこのアドレスを通じてAPIサービスにアクセスします。
Postmanとは異なり、ApidogはOpenAPI規格に従うことを推奨しています。APIにはPathのみを記入し、完全なURLを記入する必要はありません。「サービス (Base URL)」は環境に設定し、実行時にApidogが自動的に「サービス (Base URL)」をPathの前に追加します。Pathには追加の変数を含める必要はありません。
ApidogはOpenAPI規格に従うことを推奨しており、APIパス(Path)は/で始めることで、APIがより規範的になり、Apidogを使用する過程でより良く、より完全な機能体験を得ることができます。
Pathを / で始めることを推奨する理由
Pathを/で始めることは、OASに準拠するために推奨される。Pathを/で始めないと、OpenAPIエコシステム内のツールを使用する際に様々な互換性の問題が発生する可能性がある
また、Pathの先頭に/を使用することで、Apidogでテストと検証に不可欠なURLパターンモック機能を利用できる

リクエストメソッド#

リクエストメソッドは、クライアントがサーバーサイドのリソースとどのように対話するかを決定する。各メソッドは独自のセマンティクスを持ち、サーバーのレスポンスを指示する。APIを設計する際は、意図した操作を効果的に実行するために、ビジネス要件に基づいて最適なリクエストメソッドを選択する。
一般的に使用されるAPIリクエストメソッドは以下の通り:
1.
GET: 副作用なく指定されたリソースを取得。Queryパラメータを使用してデータを送信
2.
POST: 処理用のデータを送信し、副作用がある可能性がある。通常データはリクエストボディで送信
3.
PUT: 指定されたリソースを完全に更新または置換
4.
DELETE: 指定されたリソースを削除
5.
OPTIONS: 対象リソースがサポートするHTTPメソッドを問い合わせ
6.
HEAD: GETと似ているが、レスポンスヘッダーのみを取得。リソースコンテンツをダウンロードせずにリソースの存在と変更を確認するのに有用
7.
PATCH: 指定されたリソースの部分的な情報を更新
8.
TRACE: サーバーが受信したリクエストを返す。主にデバッグと診断目的で使用
9.
CONNECT: サーバーへのトンネルを確立。通常、プロキシサーバーのリクエスト転送に使用

APIメタデータ#

Apidogでは、APIにはデフォルトのメタデータフィールドが付属しており、APIのドキュメント、アクセシビリティ、ライフサイクルを定義・管理する。
各デフォルトメタデータフィールドの概要:
名前
APIの機能を概説する説明的な名前
ステータス
デフォルトのステータスは「開発中」。「APIステータス」で開発、テスト、本番などの異なる段階を反映するように変更できる
APIステータスについて詳しく見る。
担当者
APIを担当するApidogチームメンバーを指定。アカウントからユーザーを選択して役割を割り当てる
タグ
APIを分類または説明するキーワードやフレーズ。入力して新しいタグを作成するか、既存のタグから選択できる
サービス
APIパスが追加されるベースURL。デフォルトでは「親から継承」に設定されているが、インターフェース右上の環境設定で手動で指定可能
環境とサービスについて詳しく見る。
オペレーションID (operationId)
API内でこの操作を区別するための一意の識別子(OASのoperationId)
説明
APIの目的と使用方法に関する詳細情報。拡張フォーマット用にMarkdownをサポート
標準のメタデータフィールドに加えて、カスタムフィールドを追加 してAPIのメタデータをさらに充実させることができる。

リクエスト#

Requestパラメータ#

Requestパラメータは、データの返却を制御したり、サーバーのレスポンスを変更したりするためにリクエストと共に渡すことができるオプションだ。
Requestパラメータには、Queryパラメータ、Pathパラメータ、Headerパラメータ、Bodyパラメータがある。

Queryパラメータ#

Queryパラメータは、URLの末尾に疑問符 '?' の後に追加され、& で区切られるキーと値のペアで、以下のような形式になる: ?id=2&status=available。APIの出力をフィルタリング、ソート、または変更するために使用される。
Apidogでは、明確さと整理のためにQueryパラメータは別のセクションで記述される。ただし、リクエスト送信時には、これらのQueryパラメータは上記の方法でAPIパスと連結される。

Pathパラメータ#

PathパラメータはAPI URLの一部であり、API内の特定のリソースやエンティティを識別するために使用される。
Apidogでは、Pathパラメータはコロンではなく中括弧で示される。正しい例: /pets/{id} 、誤った例: /pets/:id。
Pathパラメータを追加するには、APIパスに{ パラメータ }を追加するだけで、パラメータは自動的に「 Pathパラメータ 」領域に表示される。
{パラメータ}と{{変数}}を混同しないこと
{パラメータ}:単一の中括弧は、ApidogでPathパラメータを表すために使用される。PathパラメータはAPIにアクセスする際に特定の値に動的に変化するURLパスのプレースホルダーだ。
{{変数}}:二重の中括弧は、Apidogでリクエスト内に変数を含めるために使用される。これらの変数は、リクエスト送信時に実際の値で置き換えることができ、API連携での動的でカスタマイズ可能な入力を可能にする。
パスで{{変数}}を使用することが推奨されない理由
{{変数}}を使用することはOASに準拠していない。OASに従うことで、OpenAPIエコシステム内の様々なツールとシームレスに統合できる。
パスで{{変数}}を使用すると、ApidogのURLパターンモック機能が使用できなくなる。

Headerパラメータ#

Headerパラメータは、リクエストに関する追加情報を提供し、通常、認証、コンテンツタイプ、その他のメタデータに使用される。
Headerパラメータについて詳しく見る。

Bodyパラメータ#

Bodyパラメータには、リクエストのボディで送信されるデータが含まれ、通常、POST、PUT、PATCHリクエストでリソースを作成または更新するために使用される。データは通常、JSONまたはXML形式で送信される。
Bodyパラメータについて詳しく見る。

パラメータの説明#

パラメータは名前、タイプ(文字列、整数、真偽値など)、必須性(必須またはオプション)、デフォルト値や制約を含めて説明する必要がある。
パラメータを説明する際、以下の主要なプロパティがよく使用される:
1.
名前: nameプロパティは、説明されるパラメータの名前を指定する。これは必須フィールドで、定義されるパラメータを正確に表現する必要がある。
2.
タイプ: type プロパティは、パラメータ値のデータタイプを指定する。一般的な type 値には、string、number、integer、boolean、array、object などがある。このプロパティは、パラメータ値の形式と構造を定義し、APIユーザーがリクエストを行う際に期待されるデータ形式を理解できるようにする。
3.
説明: description プロパティは、パラメータに関する簡単な説明やドキュメントを提供する。ユーザーがパラメータの目的と使用方法を理解するのに役立つ。
4.
必須: required プロパティは、パラメータがAPIリクエストに必須かどうかを指定する。パラメータがリクエストに含まれなければならないかどうかを示すブール値(true または false)だ。
5.
詳細設定: 詳細設定 プロパティは、パラメータのデータタイプ、フォーマット、制約を定義する。パラメータ値の期待される構造と内容に関する詳細情報を提供できる。
タイプエディタを使用してパラメータの詳細設定を効率的に変更できる。タイプエディタについて詳しく見る。

Schemas#

Bodyパラメータのタイプが JSON または XML の場合、データ構造を設定する必要がある。データ構造は Schema を参照できる。
Schemaについて詳しくは、Schemaを参照。

レスポンスと例#

APIにリクエストを送信した後、サーバーはレスポンスを返す。期待されるレスポンスを定義し、説明的な例を提供することは、APIを利用する開発者の理解と使いやすさを向上させる重要なステップだ。
返されるレスポンスの定義には、主に以下の部分が含まれる:
1.
HTTPステータスコード: APIが返す可能性のあるすべてのレスポンスステータスを決定する。200(OK)、404(Not Found)、500(Server Error)などの標準的なレスポンスを含む。
2.
データ形式: 各ステータスコードに対してAPIが返すレスポンスの形式を定義する。これはJSON、XML、HTML、Raw、Binary、その他の適切な形式で設定できる。
3.
Schema: データを含むレスポンス(主に200ステータス)について、レスポンスペイロードの構造を詳細に説明する。タイプ、ネストされたオブジェクト、オプションフィールド、配列の指定を含む。明確な定義により、クライアント開発者は期待されるデータとその解析方法を理解できる。SchemaはJSONとXMLのみで設定可能。
Schemaについて詳しくは、Schemaを参照。
4.
例: レスポンスの例を提供することは、実際のシナリオでAPIがどのように動作するかを示すために不可欠だ。例は、事前に定義されたリクエストでAPIにアクセスした際にサーバーが返すサンプルデータセットであるべきだ。レスポンスのSchemaで定義された構造、データ形式、タイプを反映する必要がある。

レスポンスの追加#

一般的に、APIドキュメントでは、各APIに少なくとも1つの成功レスポンスと1つのエラーレスポンスを定義することを推奨する。この実践により、様々な潜在的な結果を包括的にカバーし、開発者が異なるシナリオでのAPIの動作を明確に理解できる。
レスポンスモジュールの右上にある + 追加ボタンをクリックしてレスポンスを追加する。
通常、API設計では、200 OK の成功レスポンスは異なる出力データのニーズにより各APIで異なるが、400 Bad Request や 404 Not Found などのエラーレスポンスは異なるAPI間で一貫している傾向がある。Apidogはレスポンスコンポーネント 機能でこの共通性に賢く対応し、事前定義されたエラーレスポンスの再利用を可能にし、APIドキュメント作成プロセスをより効率的にし、APIの動作をより一貫したものにする。
レスポンスコンポーネントについて詳しく見る。
レスポンスコンポーネントが不要な場合は、空のレスポンスを追加 を選択して個々のAPIで固有のレスポンスを定義できる。

レスポンス例の追加#

「例を追加」をクリックして、Apidogにレスポンス例を含める。
1つのレスポンスには複数の異なる例を含めることができる。例を追加する際は、例の名前と対応するレスポンスデータを提供する。

自動例生成#

自動生成 をクリックすると、レスポンスSchemaの定義に基づいて、Apidogが合理的なレスポンスデータを生成する。

APIのプレビュー#

APIの仕様を完了したら、「保存」をクリックして変更を保存する。その後、「API」タブに切り替えて、設定したAPIをプレビューできる。
Previous
一括API管理
Next
複数のリクエストボディ例の設定
Built with