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のドキュメント、アクセシビリティ、ライフサイクルを定義・管理する。 ステータス
担当者
タグ
サービス
オペレーションID (operationId)
説明
リクエスト# リクエストパラメータ# リクエストパラメータは、データの返却を制御したり、サーバーのレスポンスを変更したりするためにリクエストと共に渡すことができるオプションだ。 リクエストパラメータには、クエリパラメータ、パスパラメータ、ヘッダーパラメータ、ボディパラメータがある。 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パターンモック機能が使用できなくなる。
ヘッダーパラメータ# ヘッダーパラメータは、リクエストに関する追加情報を提供し、通常、認証、コンテンツタイプ、その他のメタデータに使用される。 ボディパラメータ# ボディパラメータには、リクエストのボディで送信されるデータが含まれ、通常、POST、PUT、PATCHリクエストでリソースを作成または更新するために使用される。データは通常、JSONまたはXML形式で 送信される。 パラメータの説明# パラメータは名前、タイプ（文字列、整数、真偽値など）、必須性（必須またはオプション）、デフォルト値や制約を含めて説明する必要がある。 パラメータを説明する際、以下の主要なプロパティがよく使用される： 1.
名前 : nameプロパティは、説明されるパラメータの名前を指定する。これは必須フィールドで、定義されるパラメータを正確に表現する必要がある。
2.
タイプ : type プロパティは、パラメータ値のデータタイプを指定する。一般的な type 値には、string、number、integer、boolean、array、object などがある。このプロパティは、パラメータ値の形式と構造を定義し、APIユーザーがリクエストを行う際に期待されるデータ形式を理解できるようにする。
3.
説明 : description プロパティは、パラメータに関する簡単な説明やドキュメントを提供する。ユーザーがパラメータの目的と使用方法を理解するのに役立つ。
4.
必須 : required プロパティは、パラメータがAPIリクエストに必須かどうかを指定する。パラメータがリクエストに含まれなければならないかどうかを示すブール値（true または false）だ。
5.
詳細設定 : 詳細設定 プロパティは、パラメータのデータタイプ、フォーマット、制約を定義する。パラメータ値の期待される構造と内容に関する詳細情報を提供 できる。
タイプエディタを使用してパラメータの詳細設定を効率的に変更できる。タイプエディタ について詳しく見る。
Schemas# ボディパラメータのタイプが JSON または XML の場合、データ構造を設定する必要がある。データ構造は 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のみで設定可能。
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をプレビューできる。 
