General Usage
Fetching Single Object
The following is an example HTTP GET request for fetching a single Source object from the API:
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.comTo perform the request using 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"The resulting response document will look similar to:
{
"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": {
...
},
...
}
}If a corresponding object does not exist for the given resource, a 404 error will be returned. See the Errors section to learn more about error documents.
Fetching List of Objects
To fetch a list of objects, the request is largely the same except that it is making a GET request to a set of objects rather than a single object.
The following is an example HTTP GET request for fetching a list of Source objects from the API:
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.comTo perform the request using 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"The resulting response will contain zero or more Source objects and some paging metadata:
{
"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
},
...
}
}Specifying The Fields returned
By default, all available object fields are returned in a response. The developer can control which specific fields are returned on a per-object basis using the fields parameter. The value of this parameter is a comma-delimited list of fields to include. Any unrecognized field names will be ignored. To request a deeply-nested field, use dot notation.
An example of a request limiting the fields of a Source object would look like the following:
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.comTo perform the request using 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"The resulting response will look similar to:
{
"data": {
"attributes": {
"deployment": {
"default_params": {
"auto": "compress"
}
},
"deployment_status": "deployed",
"name": "example-source"
},
"id": "5d46fb3bd596f100018e123f",
"type": "sources"
},
...
}Paging Lists of Objects
All list API calls support paging. However, depending on the nature of the object being listed, the paging model may differ. Refer to the object-level documentation to determine what the paging model is for that object type.
In all cases, sensible defaults are in place if you do not supply explicit paging values. Not providing paging values will not result in the entire list of objects being returned. Furthermore, page sizes and cursor limits have maximum values in order to ensure good performance. Therefore, to fetch an entire list of objects, developers will need to chain together multiple API list calls in sequence and collect the results themselves.
Paging By Page Numbers and Size
The vast majority of objects support paging by page number and size. This is the default behavior when the size of the dataset is easily determined behind the scenes. To request a specific page, developers provide the page[number] and page[size] parameters. Page numbers are zero-indexed. Page sizes must be greater than or equal to 1.
The following is an example HTTP GET request for fetching a list of Source objects, one at a time, from the API:
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.comTo perform the request using 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"The resulting response document will contain one Source object at a time and paging metadata that indicates how to navigate to get the remaining pages:
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
},
...
}
}Developers should rely on the hasNextPage and nextPage values of the pagination metadata to determine if there is a next page and if there is, what that page number should be. Similarly, they can use the hasPreviousPage and previousPage values to navigate backwards. For direct access to pages, developers can build off of the currentPage and totalPages values.
Sorting Lists of Objects
Lists of objects may be sorted by a defined subset of their object fields. To sort a list by a specific field or set of fields, developers should provide the sort parameter in the request. The value should be set to a comma-separated list of valid fields of the object type. Fields are sorted ascending by default. To sort a field in descending order, prepend a dash “-” to the field name. When sorting on a Boolean type field, the default sort order is false first, then true. To reverse this order prepend a dash “-” to the field name.
Note that sorting by nested fields (e.g. deployment.type) is not currently supported.
The following is an example HTTP GET request for fetching a list of Source objects that are sorted alphabetically by name:
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.comTo perform the request using 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"The resulting response document will contain Source objects sorted by their name in alphabetical order:
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"
}
]
}Filtering Lists of Objects
Developers can filter down their lists of objects by using the filter parameter. The filter parameter is an indexed parameter with the index being the name of the field to be filtered by and the value is what to filter. Multiple filter values will be AND’ed together.
Unless noted otherwise, filter fields that take in String values will do substring matching. For example, if filter[name] is set to test, the API will return objects that have name values of test, my test, testing, etc.
Objects can define their own supported filter fields and what the values that they capture actually represent in the filter. Read the object-level documentation to learn more about which fields can be filtered and what the behavior of the values are. Unrecognized filter fields will be ignored.
For example, if a developer wanted to filter a list of Source objects to only include Sources with type s3 and with a name containing 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.comTo perform the request using 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"The resulting response document will contain Source objects that are type s3 and have names that contain 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
}
}
}Creating Objects
To create an object, developers should make an HTTP POST request to the list endpoint of the object. The document posted should include all required attributes and the object type. Optional attributes will be filled with default values. Unless otherwise specified in the object-level documentation, the id field should be left unset as it will be populated during object creation.
The following example creates a new Source object.
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"
}
}To perform the request using 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"The resulting response document will contain a Source with a new id value set. Note that the resulting response code will be 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"
},
...
}Updating Objects
To update the fields on an existing object, developers should execute an HTTP PATCH request against that object. Fields not included in the provided document will not be updated and will keep their existing values.
The id of the object and the type of the object are always required as part of PATCH requests, as per the JSON:API spec.
Note that when updating fields with values that of types List or Object, an update will replace that entire List or Object. If you would like to keep any previous values you will need to include them in the PATCH request.
The following example updates an existing Source object.
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"
}
}To perform the request using 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"The resulting response document will always include the updated Source record provided that the object exists. Otherwise, it will return a 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"
},
...
}