安定性

現在の API は安定していると考えられます。下位互換性のない変更は行いません。ただし、現在利用できない新しい機能や概念が含まれる可能性のある v1 API レイヤーに取り組む予定です。

オブジェクト キーでは大文字と小文字が区別されます。

オブジェクトに新しいフィールドを追加することは、非破壊的な変更とみなされます。

応答

成功レスポンス

リクエストが正常に完了すると、HTTPステータスコードは次のように設定されます。 200 OK別途記載がない限り。単一のオブジェクトを返すすべての応答の場合、そのオブジェクトはルート要素として返されます。 オブジェクトの配列を返すレスポンスは、配列をdata分野。

例：

{"id":"137262b4-7982-4013-a40d-74cca237fe3f",// other fields}

データを返さないエンドポイントの場合、空のオブジェクトが返されます。

エラー対応

クライアント エラーとサーバー エラーの両方で、1 つのオブジェクトが返されます。

• error 、障害の種類を示す特定のエラー コード。このフィールドは常に存在します。
• message 、エラーの原因に関する追加情報を含む、人間が読める文字列。このフィールドはマシンで使用するためのものではなく、クライアント アプリケーションのデバッグを容易にするために提供されています。存在が保証されるものではありません。

例：

// 404 {"error":"NOT_FOUND","message":"No sample with ID `00000000-0000-0000-0000-000000000000`"}

クライアントエラー

クライアントエラーによって発生したすべてのエラーの場合、HTTPステータスコードは次の範囲の値に設定されます。 [400,499] .

一般的なクライアント エラー:

• 400, "BAD_REQUEST" : リクエストのデコード中にエラーが発生しました。
• 400, "INVALID" : 1 つ以上の必須フィールドに許可されていない値が入力されています。
• 401, "UNAUTHORIZED" : 認証情報が欠落しているか無効です。
• 404, "NOT_FOUND" : オブジェクトが見つからないか、エンドポイントが存在しません。
• 405, "METHOD_NOT_ALLOWED" : エンドポイントではメソッドが許可されていません。

サーバーエラー

サーバーによるサーバーの場合、HTTPステータスコードは次のように設定されます。 500 Internal Server Error 。クライアントはリクエストを再試行できます。

• 500, "INTERNAL" : 要求は有効でしたが、サーバーはそれを処理できませんでした。

認証

すべての API リクエストは、API トークンを使用して認証する必要があります。トークンを取得できますアカウントページ。このトークンは、 Authorization HTTP ヘッダー。例：

承認: ベアラー <apikey>

ページネーション

コレクションを返すエンドポイントは、個別のリクエストを使用してコレクション全体を反復処理するページネーション スキームをサポートします。

ページ区切りは、次の 2 つのクエリ パラメータを使用して制御できます。

• limit 、応答で返される項目の最大数。 デフォルトは 50 で、API で許可される最大値は 200 です。
• offset 、前のページで返されたオブジェクトを返し始めるオフセット。省略した場合は最初のページが返されます。この値は、将来の API の変更との互換性を維持するために、不透明な文字列として扱う必要があります。

レスポンスは通常のレスポンスオブジェクトで、 dataフィールド、返されたページ内のオブジェクトを含む配列、およびnextフィールドはoffset次のページの。次のページに要素が 0 個含まれる場合は省略されます。

設定offset範囲外の値や空のコレクションをクエリすると、常に次のページが返されます。 data空の配列である。

時間

すべてのタイムスタンプは、RFC3339 形式の文字列で UTC として返されます。例： 2019-04-05T14:28:15Z