Atlas Administration API リファレンス

HTTPメソッド

すべてのリソースは、次の一般的なHTTPメソッドのサブセットをサポートしています。

JSON

すべてのエンティティはJSONで表されます。 次のルールと規則が適用されます。

• コンテンツタイプリクエストヘッダー

  POSTまたはPUTを介してサーバーにJSONを送信する場合は、必ず正しいコンテンツタイプのリクエスト ヘッダーを指定してください。 Content-Type: application/json

• 無効なフィールド

  無効なフィールドは無視されるのではなく拒否されます。 たとえば、新しいエンティティを作成してフィールドの 1 つのスペルをうっかり間違えた場合、または既存のエンティティを更新して変更できないフィールドを含めようとすると、サーバーは 400 のステータス コードと以下を示すエラーメッセージを返します。フィールドが無効です。

• ISO-8601-形式の日付

  すべての日付は、UTC で指定された ISO- 形式の文字列として返されます。8601サーバーに日付を送信する場合（つまり、POST または PATCHリクエストエンティティのクエリ パラメータまたはフィールドとして）は、ISO- 8601 形式の日付を使用します。タイムゾーンを指定しない場合は、UTC が想定されます。 ただし、あいまいさを避けるために、タイムゾーン指定子を含めることを強くお勧めします。

• BSON タイムスタンプ

  場合によっては、タイムスタンプがBSON タイムスタンプとして返されることもあり、特にバックアップ リソースに含まれます。 これらは、 JSONドキュメントでは 2 つのフィールドを持つオブジェクトとして表されます。date は 2 番目の粒度を持つ UTC の ISO-8601 形式の日付stringで、increment は 32 ビット整数です。

• 数値を含むフィールドのフィールド名

  特定の単位の数値を含むフィールドには、使用される単位を明確に区別するために名前が付けられます。

• 空のフィールド

  現在の値がないフィールドは、適切なデフォルト値とともに返されます。

  認識可能なデフォルト値を持たないフィールドは、エンティティから省略されます。

• フィールドの順序

  サーバーによって返されるJSONドキュメント内のフィールドは特定の順序ではなく、順序が変更される可能性があります。 フィールドの順序に依存しないでください。

リンク

各リソースには、サブリソースや関連リソースへの 1 つ以上のリンクが含まれています。 リンクは、リンク関係オブジェクトの配列であるエンティティのlinksフィールドに配置されます。 各リンク関係には 2 つのフィールドがあります。

すべてのエンティティには、 selfと呼ばれるリンク関係が少なくとも 1 つ含まれます。これはつまり、独自のURLです。 エンティティがリストの一部である場合、そのエンティティにはselfリンク関係のみが含まれます。

詳細については、「 Web リンク仕様 」を参照してください。 。この仕様ではHTTPレスポンス ヘッダーにリンクを含めるための形式について説明していますが、これは必須ではないことに注意してください。 Atlas Administration API を簡単に参照できるようにするには、レスポンス ヘッダーではなくレスポンス本文にリンクを含めます。

リスト

一部のリソースはエンティティのリストを返します。 応答でエンティティのリストが要求される場合、結果は次のクエリ パラメーターに囲まれたバッチで返されます。

応答エンティティには、次の 3 つのフィールドが含まれています。

エンティティのリストのリクエストを行って結果がない場合、Atlas Administration API は 200 のステータス コードを返し、 results配列は空になります。 この場合、エンティティのリストが将来のある時点で空ではなくなる可能性があるため、この場合は 404 では応答しません。 ただし、存在しないコンテキストのエンティティのリスト（存在しないプロジェクトのホストのリストなど）を要求すると、応答ステータスは404 になります。

エンベロープ

一部のクライアントは、 HTTPレスポンス ヘッダーやステータス コードにアクセスできない場合があります。 その場合は、レスポンスに「エンベロープ」を含めることをリクエストできます。これはJSONドキュメントの追加レイヤーで、レスポンス ヘッダーに通常含まれる関連詳細が含まれます。 デフォルトでは、Atlas Administration API のエンベロープに応答は含まれません。 リクエストするには、クエリ パラメータenvelope=trueを追加します。

単一のエンティティを含む応答の場合、エンベロープには 2 つのフィールドが含まれます。

エンティティのリストを含む応答の場合、結果をラップするエンベロープはすでにあるため、 envelope=trueを指定すると既存のエンベロープにstatusフィールドのみが追加されます。

Pretty Printing（整形表示）

デフォルトでは、サーバーによって返されるJSONから余計な空白が削除されます。 pretty-printed JSONをリクエストするには、リクエストにpretty=trueクエリ パラメータを追加します。

curl --user '{USERNAME}:{APIKEY}' --digest \
  --header 'Accept: application/json' \
  --include \
  --request GET "https://cloud.mongodb.com/api/atlas/v1.0?pretty=true"

応答コード

応答では、次のような標準のHTTP応答コードが使用されます。

Errors

リクエストがエラーを返す場合、レスポンス本文にはJSONドキュメントが含まれます。 このドキュメントには、Atlas Administration API リクエストが失敗した理由に関する詳細が含まれています。 ドキュメントには、次の 5 つのパラメータが含まれています。

1
{
2
  "detail" : "Cannot find resource /api/atlas/v1.0/softwareComponents/version.",
3
  "error" : 404,
4
  "errorCode" : "RESOURCE_NOT_FOUND",
5
  "parameters" : [ "/api/atlas/v1.0/softwareComponents/version" ],
6
  "reason" : "Not Found"
7
}

プロジェクトID

プロジェクト ID は、Atlas プロジェクトを一意に識別する string 値です。

Atlas プロジェクトは、以前は「グループ」として識別されていました。 一部の Atlas エンドポイントは、リクエスト パス、クエリ、またはボディ パラメータの一部としてgroupまたは{GROUP-ID}を参照します。 {GROUP-ID}を必要とするエンドポイントについては、代わりにプロジェクト ID を指定します。

プロジェクト ID を検索するには、次の手順に従います。

認証

Atlas Administration APIでは、リクエストを認証するために 2 つの方法 （ APIキーまたはサービスアカウント）のいずれかを使用します。これにより、ユーザー名とパスワードとして機能するキーとアクセス トークンがネットワーク経由で送信されることがなくなります。 詳細については、 「Atlas Administration API認証」 を参照してください。

使用方法の詳細については、「 APIリクエストの作成 」を参照してください。

レート制限

特定のリソースでは、1 分あたりに処理できるリクエスト数が制限されます。

これらのリソースに対して、Atlas はプロジェクトごとに100 1 分あたり最大 のリクエストを許可します。Atlas Administration API認証メソッドは組織に属しますが、複数のプロジェクトへのアクセス権を付与できます。

レート制限を超えた場合、Atlas Administration API は429 を返します （リクエストが多すぎる） HTTP ステータス コード。

次のステップ

使用を開始するには、「 Atlas Administration API の使い始める 」を参照してください。

プログラムによる Atlas Administration API へのアクセスを管理するには、次のいずれかの手順を参照してください。

• プログラムによる組織へのアクセスを管理します。

• プログラムによる複数の組織へのアクセスを管理します。

• プログラムによるプロジェクトへのアクセスを管理します。