Following the deprecation announcement back in October 2020 for legacy imgix API keys, we are on schedule to deprecate the use of legacy APIs on March 31, 2021.
Note that this applies only to the API for retrieving reports and for purging images. The API to render images is unaffected and will continue to function as it does today.
If you are still using imgix’s legacy API, you must migrate to imgix’s new API to ensure calls to the imgix service will remain successful. To do so, follow the guide below to migrate to imgix’s new API.
How To Tell If You Will Be Impacted
The easiest way to tell if you’re using the imgix legacy API is to examine the endpoints currently being used.
If you are using any of these endpoints, you must migrate over to the new API:
https://api.imgix.com/v2/image/purgerhttps://api.imgix.com/v2/account/reports
You can also check your authentication method. The legacy API uses Basic authentication, while the new API uses Bearer authentication.
Note that we’re deprecating only these two API endpoints. The rendering API is not affected by this deprecation date.
If you are still using the legacy API, continue reading to learn how to migrate over to the new API.
Generating New API Keys
All legacy API keys will be invalidated in March 2021. Before then, you will need to create new keys in order to authenticate calls to the service.
To do this, access the API keys logging into your dashboard in your dashboard and clicking your account at the top right to navigate to the API Keys page.
The new API keys allow for scoped permissions depending on the type of API access you want to grant. For the purging API, you must have purging permissions. For the reporting API, you must have analytics permissions.
The permissions a user can grant an API key will depend on the permissions they have on their own user role. If you are lacking the right permissions, contact an account administrator to add permissions to your user account. The tutorial for adding users can be found here.
Note that generating new API keys will not invalidate your existing legacy API keys, so feel free to create new API keys for testing before you migrate over to the new API.
Convert Your Authentication Method
The legacy authentication method used a combination of basic authentication and a base64 encoded version of your legacy API token. You can see an example of the legacy authentication method below:
POST /v2/image/purger HTTP/1.1
Accept: application/vnd.api+json
Authorization: Basic <base64-api-key>
Content-Type: application/json
Host: api.imgix.comThe new API uses bearer authentication and no longer requires that you base64 encode the API key.
Here’s an example authentication request using the new API:
POST /api/v1/purge HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.comThe Content-Type and Accept header values have also changed. You must now specify Content-Type: application/vnd.api+json when sending making requests to our API.
New Endpoints
The legacy API uses the endpoint endpoint https://api.imgix.com/v2/ for API requests.
The new API uses this endpoint: https://api.imgix.com/api/v1. The paths for the purging and reporting endpoint have also changed, so continue reading to learn how to migrate both of those endpoints.
Why we are changing from /v2/ to /api/v1/
The new migration is more than an upgrade, it’s a completely new set of endpoints to interact with a broader range of services that imgix offers. Because of that, we decided to refresh our endpoint version by restarting with /v1/.
Purging API
The purging API has been upgraded to include sub-image purging. It has also been standardized to require more data in order complete purge requests.
Legacy API
To compare, here’s an example of purging an image using the legacy API:
POST /v2/image/purger HTTP/1.1
Accept: application/json
Authorization: Basic <base64-api-key>
Content-Type: application/json
Host: api.imgix.com
{
"data": {
"url": "https://assets.imgix.net/examples/bridge.jpg"
}
}New API
The new purging API specifies the image to purge using the attributes object:
POST /api/v1/purge HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com
{
"data": {
"attributes": {
"url": "https://assets.imgix.net/examples/bridge.jpg"
},
"type": "purges"
}
}The new purging API also supports purging sub-images. To do this, read the sub-image purging section in our Management API documentation.
Reporting API
The reporting API has a few changes concerning sorting, filtering and result limiting.
To compare, here is an example request using the legacy API:
GET /v2/account/reports?limit=5&sort=report_key&order=desc&offset=9 HTTP/1.1
Accept: application/json
Authorization: Basic <base64-api-key>
Content-Type: application/json
Host: api.imgix.comHere is that same request using the new reporting API:
GET /api/v1/reports?page[number]=3&page[size]=5&sort=-report_key HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.comLegacy Sorting Method
Previously, you could sort reports in descending order by using either order=desc or order=asc:
GET /v2/account/reports?limit=5&sort=report_key&order=desc HTTP/1.1
Accept: application/json
Authorization: Basic <base64-api-key>
Content-Type: application/json
Host: api.imgix.comNew Sorting Method
The new API specifies sorting by defaulting to ascending order. To reverse order, prepend - to the sort value. The following example sorts by report_key in descending order by using the new API:
GET /api/v1/reports?sort=-report_key HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.comLegacy Pagination Method
The new API introduces pagination, which replaces the legacy limit functionality in the previous reporting API.
Here is an example of limiting results by using the legacy API:
GET /v2/account/reports?limit=5 HTTP/1.1
Accept: application/json
Authorization: Basic <base64-api-key>
Content-Type: application/json
Host: api.imgix.comNew Pagination Method
The example below returns exactly one result from page 1 of the response:
GET /api/v1/reports?page[number]=1&page[size]=1 HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.comWith the new API, there are two new parameters to use to limit the size of the response. These are:
page[number]page[size]
page[number] will specify the page of the results to return. For example, if the full response is 6 pages long, page[number]=3 will return page 3 of the results.
page[size] specifies the size of the results on each page. Using a value such as page[size]=1 will return exactly 1 result per page.
The documentation for using pagination can be found in the management API documentation.
Postman Collections
Are you looking to explore the new functionality offered by imgix’s new API? If you have Postman downloaded, you can import the imgix API collection into Postman for an organized list of imgix API examples to try out. Download it here.
The collection uses variables to help you get up and running with testing. After you import the collection to Postman, you can insert your Source ID, API key and other values by using Postman’s variables feature.
Still Need Help?
Still having trouble with migrating to the new API? If so, contact support@imgix.com and we will be happy to guide you.