一般的な使い方

単一オブジェクトの取得

以下は、API から単一のソースオブジェクトを取得するための HTTP GET リクエストの例です:

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

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

curl \
  -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/5d46fb3bd596f100018e123f"

結果のレスポンスは次のようになります:

{
  "data": {
    "attributes": {
      "date_deployed": 1591042615,
      "deployment": {
        "annotation": "New deployment created for source by imgix testing.",
        "cache_ttl_behavior": "respect_origin",
        "cache_ttl_error": 300,
        "cache_ttl_value": 31536000,
        "crossdomain_xml_enabled": false,
        "custom_domains": [],
        "default_params": {},
        "image_error": null,
        "image_error_append_qs": false,
        "image_missing": null,
        "image_missing_append_qs": false,
        "imgix_subdomains": [
          "my-unique-domain"
        ],
        "secure_url_enabled": false,
        "type": "webfolder",
        "webfolder_base_url": "http://my-domain.com/images/"
      },
      "deployment_status": "deployed",
      "enabled": true,
      "name": "New Web Folder Source"
    },
    "id": "5ed56238a04d080001d4a08e",
    "type": "sources"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "authentication": {
      ...
    },
  ...
  }
}

指定されたリソースに対応するオブジェクトが存在しない場合、404 エラーが返されます。エラードキュメントについて詳しくはエラーのセクションを参照してください。

オブジェクトのリストの取得

オブジェクトのリストを取得するには、リクエストは基本的に同じですが、単一のオブジェクトではなくオブジェクトのセットに対して GET リクエストを行います。

以下は、API からソースオブジェクトのリストを取得するための HTTP GET リクエストの例です:

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

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

curl \
  -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"

結果のレスポンスには、ゼロ個以上のソースオブジェクトとページングメタデータが含まれます:

{
  "data": [
    {
      "attributes": {
        ...
      },
      "id": "5d1e0dc3d596f10001b0221c",
      "type": "sources"
    },
    {
      "attributes": {
        ...
      "id": "5ae509aaf5b98f000169ee72",
      "type": "sources"
    },
  ],
  ...
  "meta": {
    ...
    "pagination": {
      "currentPage": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "nextPage": 0,
      "pageSize": 20,
      "previousPage": 0,
      "totalPages": 1,
      "totalRecords": 2
    },
    ...
  }
}

返されるフィールドを指定する

デフォルトでは、レスポンスには利用可能なすべてのオブジェクトフィールドが返されます。開発者は、fields パラメータを使用して、オブジェクトごとに返される特定のフィールドを制御できます。このパラメータの値は、含めるフィールドのコンマ区切りリストです。認識されないフィールド名は無視されます。深くネストされたフィールドを要求する場合は、ドット表記を使用します。

ソースオブジェクトのフィールドを制限するリクエストの例は次のようになります:

GET /api/v1/sources/5d46fb3bd596f100018e123f?fields[sources]=name,deployment_status,deployment.default_params HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com

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

curl \
  -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/5d46fb3bd596f100018e123f?fields\[sources\]=name,deployment_status,deployment.default_params"

結果のレスポンスは次のようになります:

{
  "data": {
    "attributes": {
      "deployment": {
        "default_params": {
          "auto": "compress"
        }
      },
      "deployment_status": "deployed",
      "name": "example-source"
    },
    "id": "5d46fb3bd596f100018e123f",
    "type": "sources"
  },
  ...
}

オブジェクトのページングリスト

すべてのリスト API コールはページングをサポートしています。ただし、リストされるオブジェクトの性質によっては、ページングモデルが異なる場合があります。そのオブジェクトタイプのページングモデルを特定するには、オブジェクトレベルのドキュメントを参照してください。

すべての場合において、明示的なページング値を提供しない場合は、適切なデフォルト値が設定されています。ページング値を提供しない場合でも、オブジェクトの全リストが返されるわけではありません。さらに、ページサイズとカーソルの制限は、良好なパフォーマンスを確保するために最大値が設定されています。そのため、全オブジェクトリストを取得するには、開発者は複数の API リストコールを連鎖させて結果を自分で収集する必要があります。

ページ番号とサイズによるページング

ほとんどのオブジェクトは、ページ番号とサイズによるページングをサポートしています。これは、データセットのサイズが裏で簡単に判別できる場合のデフォルト動作です。特定のページをリクエストするには、開発者は page[number] と page[size] パラメータを指定します。ページ番号はゼロベースです。ページサイズは 1 以上でなければなりません。

以下は、API からソースオブジェクトのリストを一度に1つずつ取得するための HTTP GET リクエストの例です:

GET /api/v1/sources?page[number]=0&page[size]=1 HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com

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

curl \
  -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?page\[number\]=0&page\[size\]=1"

結果の応答ドキュメントには、一度に1つのソースオブジェクトと、残りのページに移動する方法を示すページングメタデータが含まれます:

HTTP/1.1 200
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT
 
{
  "data": [
    {
      "attributes": {
        "deployment": {
          ...
        },
        "deployment_status": "deployed",
        "enabled": true,
        "name": "example-source",
        "secure_url_token": ...
      },
      "id": "5d1e0dc3d596f10001b0221c",
      "type": "sources"
    }
  ],
  ...
  },
  ...
  "meta": {
    ...
    "pagination": {
      "currentPage": 0,
      "hasNextPage": true,
      "hasPreviousPage": false,
      "nextPage": 1,
      "pageSize": 1,
      "previousPage": 0,
      "totalPages": 7,
      "totalRecords": 7
    },
    ...
  }
}

開発者は、ページネーションメタデータの hasNextPage と nextPage の値を利用して、次のページがあるかどうか、ある場合はそのページ番号を判断するべきです。同様に、hasPreviousPage と previousPage の値を使用して逆方向に移動することができます。ページへの直接アクセスには、currentPage と totalPages の値を基に構築することができます。

オブジェクトリストのソート

オブジェクトのリストは、定義されたサブセットのオブジェクトフィールドでソートできます。リストを特定のフィールドまたはフィールドセットでソートするには、開発者はリクエストに sort パラメータを指定する必要があります。値は、オブジェクトタイプの有効なフィールドのコンマ区切りリストに設定する必要があります。デフォルトではフィールドは昇順でソートされます。フィールドを降順でソートするには、フィールド名の前にダッシュ「-」を付けます。ブール型フィールドでソートする場合、デフォルトのソート順はまず false、次に true です。この順序を反転させるには、フィールド名の前にダッシュ「-」を付けます。

注意: ネストされたフィールド (例: deployment.type) でのソートは現在サポートされていません。

以下は、名前でアルファベット順にソートされたソースオブジェクトのリストを取得するための HTTP GET リクエストの例です:

GET /api/v1/sources?sort=name&fields[sources]=name HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com

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

curl \
  -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?sort=name&fields[sources]=name"

結果の応答ドキュメントには、name でアルファベット順にソートされたソースオブジェクトが含まれます:

HTTP/1.1 200
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT
 
{
  "data": [
    {
      "attributes": {
        "name": "Azure Source"
      },
      "id": "5ed8734f6734bf0001ac1145",
      "type": "sources"
    },
    {
      "attributes": {
        "name": "GCS Source"
      },
      "id": "5ed8736e956a8d0001f28424",
      "type": "sources"
    },
    {
      "attributes": {
        "name": "S3 Source"
      },
      "id": "5ed844bc6bde8a0001c08dbf",
      "type": "sources"
    }
  ]
}

オブジェクトのリストのフィルタリング

開発者は、filter パラメータを使用してオブジェクトのリストを絞り込むことができます。filter パラメータは、インデックス付きパラメータで、インデックスはフィルタリングするフィールドの名前であり、値はフィルタリングする内容です。複数の filter 値は AND で結合されます。

特に記載がない限り、文字列値を受け取るフィルタフィールドは部分一致します。たとえば、filter[name] が test に設定されている場合、API は test、my test、testing などの名前の値を持つオブジェクトを返します。

オブジェクトは、サポートされているフィルタフィールドと、フィルタでキャプチャされる実際の値が何を表すかを定義できます。フィルタ可能なフィールドと値の動作については、オブジェクトレベルのドキュメントを参照してください。認識されないフィルタフィールドは無視されます。

たとえば、開発者がソースオブジェクトのリストをフィルタリングして、タイプが s3 で name に staging が含まれるソースのみを含めたい場合は:

GET /api/v1/sources?filter[name]=staging&filter[deployment.type]=s3 HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com

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

curl \
  -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?filter\[name\]=staging&filter\[deployment.type\]=s3"

結果の応答ドキュメントには、タイプが s3 で name に staging が含まれるソースオブジェクトが含まれます。

HTTP/1.1 200
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT
 
{
  "data": [
    {
      "attributes": {
        "deployment": {
          ...
          "type": "s3"
        },
        "deployment_status": "deployed",
        "enabled": true,
        "name": "Staging 1"
      },
      "id": "5ed844bc6bde8a0001c08dbf",
      "type": "sources"
    },
    {
      "attributes": {
        "deployment": {
          "type": "s3"
        },
        "deployment_status": "deployed",
        "enabled": true,
        "name": "Staging 2"
      },
      "id": "5ed873349234930001cc74ae",
      "type": "sources"
    },
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "pagination": {
      "currentPage": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "nextPage": 1,
      "pageSize": 20,
      "previousPage": 0,
      "totalPages": 1,
      "totalRecords": 1
    }
  }
}

オブジェクトの作成

オブジェクトを作成するには、開発者はオブジェクトのリストエンドポイントに対して HTTP POST リクエストを行う必要があります。投稿されるドキュメントには、すべての必須の attributes とオブジェクトの type を含める必要があります。オプションの属性はデフォルト値で埋められます。オブジェクトレベルのドキュメントで特に指定されていない限り、id フィールドは設定されていない状態にしておく必要があります。なぜなら、オブジェクト作成中に自動的に値が設定されるからです。

次の例は、新しいソースオブジェクトを作成します。

POST /api/v1/sources HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com
 
{
  "data": {
    "attributes": {
      "name": "New Web Folder Source",
      "deployment": {
        "type": "webfolder",
        "webfolder_base_url": "https://my-domain.com/images/",
        "imgix_subdomains": [
          "my-unique-imgix-subdomain"
        ]
      }
    },
  "type": "sources"
  },
  "jsonapi": {
    "version": "1.0"
  }
}

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

curl \
  -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{ "data": { "attributes": { "name": "New Web Folder Source", "deployment": { "type": "webfolder", "webfolder_base_url": "https://my-domain.com/images/", "imgix_subdomains": [ "my-unique-imgix-subdomain" ] } }, "type": "sources"}, "jsonapi": { "version": "1.0" } }' \
  "https://api.imgix.com/api/v1/sources"

結果の応答ドキュメントには、新しい id 値が設定されたソースが含まれます。なお、結果の応答コードは 201 Created になります。

HTTP/1.1 201
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT
 
{
  "data": {
    "attributes": {
      "date_deployed": 1594942125,
      "deployment": {
        "annotation": "New deployment created for source by testing-api-docs.",
        "cache_ttl_behavior": "respect_origin",
        "cache_ttl_error": 300,
        "cache_ttl_value": 31536000,
        "crossdomain_xml_enabled": false,
        "custom_domains": [],
        "default_params": {},
        "image_error": null,
        "image_error_append_qs": false,
        "image_missing": null,
        "image_missing_append_qs": false,
        "imgix_subdomains": [
          "my-unique-domain"
        ],
        "secure_url_enabled": false,
        "type": "webfolder",
        "webfolder_base_url": "https://my-website.com/images/"
      },
      "deployment_status": "deploying",
      "enabled": true,
      "name": "New Web Folder Source"
    },
    "id": "5ed5a2b1b4e4940001e29909",
    "type": "sources"
  },
  ...
}

オブジェクトの更新

既存のオブジェクトのフィールドを更新するには、開発者はそのオブジェクトに対して HTTP PATCH リクエストを実行する必要があります。提供されたドキュメントに含まれていないフィールドは更新されず、現在の値が保持されます。

PATCH リクエストの一部として、オブジェクトの id と type は常に必要です。これは、JSON:API スペック (opens in a new tab)に準拠しています。

なお、リストまたはオブジェクト型の値を持つフィールドを更新する場合、更新はそのリストまたはオブジェクト全体を置換します。以前の値を保持したい場合は、PATCH リクエストに含める必要があります。

以下の例は、既存のソースオブジェクトを更新します。

PATCH /api/v1/sources/5d46fb3bd596f100018e123f HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com
 
{
  "data": {
    "attributes": {
      "name": "New Source Name"
    },
    "id": "5d703ed13f876f000190b31d",
    "type": "sources"
  }
}

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

curl \
  -X PATCH \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{ "data": {"attributes": { "name": "New Source Name" },"id": "5d703ed13f876f000190b31d", "type": "sources" } }' \
  "https://api.imgix.com/api/v1/sources/5d46fb3bd596f100018e123f"

結果の応答ドキュメントには、オブジェクトが存在する場合は常に更新されたソースレコードが含まれます。存在しない場合は、404 Not Found が返されます。

HTTP/1.1 200
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT
 
{
  "data": {
    ...
    "name": "New Source Name",
  },
  "id": "5d46fb3bd596f100018e123f",
  "type": "sources"
  },
  ...
}

概要アセット