マネージメント API 概要

imgix マネージメント API は、開発者がソースをプログラムで構成し、アセットに関連する他の活動を実行できるようにします。この API は REST ベースであり、JSON:API 仕様 (opens in a new tab) に準拠しています。これにより、JSON リソースを操作するための便利で一貫したインターフェースが提供されます。

imgix マネージメント API の基本 URL は https://api.imgix.com/ です。

認証

imgix マネージメント API へのすべての呼び出しには、API キーが必要です。キーを作成するには、ダッシュボードの API キー表示 (opens in a new tab) に移動します。ユーザーは誰でも API キーを作成できますが、ユーザーが作成できるキーの権限は、ユーザー自身の権限以下である必要があります。アカウント管理者は ユーザー ページ (opens in a new tab) でユーザーの権限を更新したり、こちらで権限について詳しく説明を読むことができます。

imgix は、以下の権限を マネージメント API でサポートしています:

• アカウント管理者: すべての権限
• アナリティクス: レポート API を使用して分析データを取得します。
• ソース: imgix ソースの作成、一覧表示、編集、デプロイ
• パージ: 削除されたアセットまたは古いアセットを imgix キャッシュから削除します。
• アセットマネージャーの閲覧: アセットマネージャーのすべてのコンテンツを一覧表示および取得します。
• アセットマネージャーの編集: 画像メタデータの編集およびアセットのアップロードをアセットマネージャーに行います (注: この権限には、暗黙的にアセットマネージャーの閲覧が含まれます。)

認証は、HTTP Authorization ヘッダーを介してリクエストで有効な API キーを渡すことで実行されます。API は、プレーンテキストでのアルファヌメリック API キーに続いて Bearer 認証タイプを期待します。

API リクエストの認証方法の例:

bash copy curl -H "Authorization: Bearer <your-api-key>" https://api.imgix.com/...

リクエストの作成

imgix マネージメント API は、REST および JSON:API 構造化ドキュメントを使用してオブジェクトの読み取りと書き込みを行います。実行するアクションに応じて、リクエスト構造がアクションの性質に一致するように変化する場合があります。

source_id を必要とするすべてのリクエストについては、いくつかの異なる方法でこれを見つけることができます:

• sources エンドポイントに GET リクエストを行うと、JSON 応答内の id フィールドの下にあります。

• ソースダッシュボード (opens in a new tab) で見つかったソースのいずれかに移動し、URL の最後の 24 文字の文字列をコピーします。

• ソースに移動してソース構成ページを開くと、source_id も見つかります。

  

エラー

API は、失敗した操作に遭遇したときに JSON 形式のエラーを返します。成功したリクエストで返される data 属性の代わりに、API 応答には errors 属性が含まれます。errors の値は、次のフィールドを含む個々のエラーオブジェクトのリストになります:

次の例では、存在しないソースを要求しようとしています:

GET /api/v1/sources/invalid-source HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com

curl を使用してリクエストを実行するには:

curl \
  -X GET \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  "https://api.imgix.com/api/v1/sources/invalid-source"

レスポンスには、errorについての詳細が含まれます:

HTTP/1.1 404
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT
 
{
  "errors": [
    {
      "detail": "Resource not found.",
      "id": "56ba72bdd33d4395b464fae69f0d31c7",
      "meta": {},
      "status": "404",
      "title": "NotFound"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  },
  "server": {
    ...
  }
}

レート制限

当社の API は、エンドポイントに応じて可変レート制限を持っています。リクエストが完了せず、レート制限エラーが返されないようにするには、以下のレート制限に基づいて マネージメント API のリクエストをスロットリングすることをお勧めします。

特定のエンドポイントのレート制限が超過された場合、新しい API リクエストに対して 429 Too Many Requests エラーを返します。その後、レート制限が緩和されるまで、そのエンドポイントへの新しいリクエストを拒否します。以下にレート制限を示します: