Image Manager API Resources

The Image Manager API allows you to create, list, and modify policies, and organize images.

Follow this basic workflow to create a custom Image Manager policy:

  1. Enable Image Manager on a property in Property Manager.

  2. Retrieve the Luna-Token header generated once Image Manager is enabled on a property. This header, or API key, is required for all API calls and may look something like this: default-022335.

  3. Determine which image transformations you want to include in the policy.

  4. Run the List Policies operation to to retrieve a listing of all current Image Manager policies.

  5. Review the list of policy IDs (policyId) returned.

  6. Create a Policy object.

  7. Run the Create or Modify a Policy operation, making sure to provide a new, unique policyId value. Otherwise you may overwrite an existing policy.

  8. Activate the policy on the staging network, as described below.

  9. Test the policy on the staging network.

  10. Activate the policy on the production network.

Before going live with an Image Manager policy, activate the policy on the staging network. To activate a policy, add -staging to the hostname used for the request. For example, to activate a custom policy with an ID of mobile-policy on staging, you would use this URL:

https://akab-xxxxx-xxxxxxxxxx.imaging-staging.akamaiapis.net/imaging/v2/policies/mobile-policy

To activate the default policy on staging, use this hostname:

https://akab-xxxxx-xxxxxxxxxx.imaging-staging.akamaiapis.net/imaging/v2/policies/policies/.auto

To activate the same policy on production once you’ve completed testing, you would use the regular hostname. For example:

https://akab-xxxxx-xxxxxxxxxx.imaging.akamaiapis.net/imaging/v2/policies/mobile-policy.

API Summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Policies  
List Policies GET /imaging/v2/policies
Get a Policy GET /imaging/v2/policies/{policyId}
Create or Modify a Policy PUT /imaging/v2/policies/{policyId}
Remove a Policy DELETE /imaging/v2/policies/{policyId}
Get Policy History GET /imaging/v2/policies/history/{policyId}
Images  
List Images GET /imaging/v0/images/{?limit,url,policyId}
Get an Image GET /imaging/v0/images/{imageId}
Image Collections  
List Image Collections GET /imaging/v0/imagecollections/{?limit}
Create a New Image Collection PUT /imaging/v0/imagecollections/
Get an Image Collection GET /imaging/v0/imagecollections/{imageCollectionId}
Update an Image Collection POST /imaging/v0/imagecollections/{imageCollectionId}
Delete an Image Collection DELETE /imaging/v0/imagecollections/{imageCollectionId}
Get Image Collection History GET /imaging/v0/imagecollections/{imageCollectionId}/history{?limit}

List Policies

Retrieve a list of all policies using a specific instance of the Image Manager behavior.

GET /imaging/v2/policies

Headers:

Luna-Token: default-022335

Status 200 application/json

Response Body:

{
    "totalItems": 2,
    "itemKind": "POLICY",
    "items": [
        {
            "id": ".auto"
        },
        {
            "id": "watermark"
        }
    ]
}

Get a Policy

Retrieve a specific policy associated with the selected API key.

GET /imaging/v2/policies/{policyId}

Sample: /imaging/v2/policies/thumbnail_policy

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
URL Parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Response Body:

{
    "id": "watermark",
    "transformations": [
        {
            "transformation": "Composite",
            "image": {
                "url": "www.customer.com/watermark.png"
            },
            "xPosition": 0,
            "yPosition": 0,
            "gravity": "SouthWest"
        }
    ],
    "breakpoints": {
        "widths": [
            500,
            300
        ]
    },
    "output": {
        "quality": 90
    }
}
  1. Run the List Policies operation and store the policy ID (id).

  2. Make a GET request to /imaging/v2/policies/{policyId}.

The response includes the Policy object.

Create or Modify a Policy

Create a policy or update the policy definition for a given ID. When creating a new policy, make sure the policyId doesn’t already exist.

PUT /imaging/v2/policies/{policyId}

Sample: /imaging/v2/policies/thumbnail_policy

Headers:

Luna-Token: default-022335

Content-Type: application/json

Request Body:

{
    "resolutions": {
        "widths": [
            240,
            120,
            60
        ]
    }
}
Parameter Type Sample Description
URL Parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Response Body:

{
    "operationPerformed": "UPDATED",
    "description": "Policy thumbnail_policy updated.",
    "id": "thumbnail_policy"
}
  1. Run the List Policies operation and store the policyId.

  2. Review the list of policy IDs (policyId) returned.

  3. Create a Policy object.

  4. Run the Create or Modify a Policy operation, making sure to provide a new, unique policyId value. Otherwise you may overwrite an existing policy.

The response includes the Policy object.

Remove a Policy

Delete a specific policy ID.

DELETE /imaging/v2/policies/{policyId}

Sample: /imaging/v2/policies/thumbnail_policy

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
URL Parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Response Body:

{
    "operationPerformed": "DELETED",
    "description": "Policy thumbnail_policy deleted.",
    "id": "thumbnail_policy"
}
  1. Run the List Policies operation and store the policy ID (id).

  2. Make a DELETE request to /imaging/v2/policies/{policyId}.

Get Policy History

Retrieve policy history by policy ID. This operation returns the full state of the policy at various points in time. Time stamps are in ISO–8601 extended notation format.

GET /imaging/v2/policies/history/{policyId}

Sample: /imaging/v2/policies/history/thumbnail_policy

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
URL Parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Response Body:

{
    "itemKind": "POLICIESLOG",
    "items": [
        {
            "id": "thumbnail_policy",
            "dateCreated": "2015-06-09 15:41:37+0000",
            "policy": "{\"id\":\"grayscale\",\"transformations\":[{\"transformation\":\"Grayscale\"}],\"resolutions\":{\"widths\":[500]},\"currentVersion\":1}",
            "action": "UPSERT",
            "user": "jsmith"
        }
    ],
    "totalItems": 1
}
  1. Run the List Policies operation and store the policy ID (id).

  2. Make a GET request to /imaging/v2/policies/history/{policyId}.

The response includes the History object.

List Images

List a policy’s images.

GET /imaging/v0/images/{?limit,url,policyId}

Sample: /imaging/v0/images/?limit=2&url=http%3A//www.example.com/image2.png&policyId=thumbnail_policy

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
Optional Query Parameters
limit Integer 2 Specifies maximum number images to retrieve.
policyId String thumbnail_policy The policy to list images for.
url String http://www.example.com/image2.png URL to search for.

Status 200 application/json

Response Body:

{
    "totalItems": 1,
    "itemKind": "IMAGE",
    "items": [
        {
            "id": "/images/image2.png",
            "url": "http://www.example.com/images/image2.png",
            "policies": {
                "watermark": {
                    "sizes": {
                        "200": {
                            "date": "2016-03-23 13:05:59+0000",
                            "policyVersion": 1,
                            "status": "PASSED"
                        }
                    }
                }
            }
        }
    ]
}
  1. Run the List Policies operation and store the policyId.

  2. If you want to specify the number of results to return, use the limit query parameter. If you want 10 results, add ?limit=10 to the endpoint.

  3. If you want to return images associated with a specific URL, use the url query parameter.

  4. Make a GET request to /imaging/v0/images/{?limit,url,policyId}.

The response includes the Image object.

Get an Image

Retrieve a specific image.

GET /imaging/v0/images/{imageId}

Sample: /imaging/v0/images//images/image.jpg%3FimageId%3Dformat/jpg

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
URL Parameters
imageId String /images/image.jpg?imageId=format/jpg The ID of the image. This ID usually represents the part of the URL after the scheme, host, and port.

Status 200 application/json

Response Body:

{
    "id": "/house/image1.jpg",
    "url": "http://www.example.com/house/image1.jpg",
    "policies": {
        ".auto": {
            "sizes": {
                "50": {
                    "date": "2016-03-22 13:05:59+0000",
                    "policyVersion": 1,
                    "status": "PASSED"
                }
            }
        }
    }
}
  1. Run the List Images operation and store the imageId.

  2. Make a GET request to /imaging/v0/images/{imageId}.

The response includes the Image object.

List Image Collections

Lists all image collections, unless you set a limit.

GET /imaging/v0/imagecollections/{?limit}

Sample: /imaging/v0/imagecollections/?limit=2

Parameter Type Sample Description
Optional Query Parameters
limit Integer 2 Specifies maximum number image collections to retrieve.

Status 200 application/json

Response Body:

{
    "itemKind": "IMAGECOLLECTION",
    "items": [
        {
            "id": "product-1",
            "user": "johndoe",
            "lastModifiedTimestamp": 1509418397284,
            "definition": {
                "version": 1,
                "items": [
                    {
                        "type": "image",
                        "url": "http://example.com/img1.jpg",
                        "mime": "image/jpeg"
                    },
                    {
                        "type": "image",
                        "url": "http://example.com/img2.jpg",
                        "mime": "image/jpeg"
                    }
                ]
            }
        },
        {
            "id": "product-2",
            "user": "janedoe",
            "lastModifiedTimestamp": 1509418397284,
            "definition": {
                "version": 1,
                "items": [
                    {
                        "type": "video",
                        "url": "http://example.com/vid1.mp4",
                        "mime": "video/mp4"
                    },
                    {
                        "type": "video",
                        "url": "http://example.com/vid2.webm",
                        "mime": "video/webm"
                    }
                ]
            }
        }
    ],
    "totalItems": 2
}
  1. If you want to specify the number of results to return, use the limit query parameter. If you want 10 results, add ?limit=10 to the endpoint.

  2. Make a GET request to /imaging/v0/imagecollections/{?limit}.

The response includes the ImageCollection object.

Create a New Image Collection

Create a new image collection.

PUT /imaging/v0/imagecollections/

Content-Type: application/json

Request Body:

{
    "operationPerformed": "CREATED",
    "description": "Image Collection SKU-26684355 was created",
    "id": "SKU-26684355"
}

Status 200 application/json

Response Body:

{
    "operationPerformed": "CREATED",
    "description": "Image Collection SKU-26684355 was created",
    "id": "SKU-26684355"
}
  1. Run the List Image Collections operation.

  2. Review the list of IDs (imageCollectionId) returned.

  3. Create a unique imageCollectionId for the new collection.

  4. Create an ImageCollection object.

  5. Make a PUT request to /imaging/v0/imagecollections/.

The response includes the ImageCollection object.

Get an Image Collection

Returns the values for the image collection you specify.

GET /imaging/v0/imagecollections/{imageCollectionId}

Sample: /imaging/v0/imagecollections/MyId123

Parameter Type Sample Description
URL Parameters
imageCollectionId String MyId123 Unique identifier for each image collection.

Status 200 application/json

Response Body:

{
    "id": "MyId123",
    "tags": [
        "red",
        "shoe"
    ],
    "definition": {
        "type": "Gallery",
        "items": [
            {
                "type": "AkaImage",
                "imageId": "/images/bag.front.jpg"
            },
            {
                "type": "AkaImage",
                "imageId": "/images/bag.side.jpg"
            },
            {
                "type": "AkaImage",
                "imageId": "/images/bag.back.jpg"
            }
        ]
    }
}
  1. Run the List Image Collections operation and store the imageCollectionId.

  2. Make a GET request to /imaging/v0/imagecollections/{imageCollectionId}.

The response includes the ImageCollection object.

Update an Image Collection

Update an image collection.

POST /imaging/v0/imagecollections/{imageCollectionId}

Sample: /imaging/v0/imagecollections/MyId123

Content-Type: application/json

Request Body:

{
    "operationPerformed": "UPDATED",
    "description": "Image Collection MyId123 was updated",
    "id": "MyId123"
}
Parameter Type Sample Description
URL Parameters
imageCollectionId String MyId123 Unique identifier for each image collection.

Status 200 application/json

Response Body:

{
    "operationPerformed": "UPDATED",
    "description": "Image Collection MyId123 was updated",
    "id": "MyId123"
}
  1. Run the List Image Collections operation and store the imageCollectionId you want to update.

  2. Create an ImageCollection object.

  3. Make a POST request to /imaging/v0/imagecollections/{imageCollectionId}.

The response includes the ImageCollection object.

Delete an Image Collection

Delete an image collection.

DELETE /imaging/v0/imagecollections/{imageCollectionId}

Sample: /imaging/v0/imagecollections/MyId123

Parameter Type Sample Description
URL Parameters
imageCollectionId String MyId123 Unique identifier for each image collection.

Status 200 application/json

Response Body:

{
    "operationPerformed": "DELETED",
    "description": "Item was deleted",
    "id": "MyId123"
}
  1. Run the List Image Collections operation and store the imageCollectionId.

  2. Make a DELETE request to /imaging/v0/imagecollections/{imageCollectionId}.

Get Image Collection History

Get a history of a specific image collection and all updates to it over the last three months.

GET /imaging/v0/imagecollections/{imageCollectionId}/history{?limit}

Sample: /imaging/v0/imagecollections/MyId123/history?limit=2

Parameter Type Sample Description
URL Parameters
imageCollectionId String MyId123 Unique identifier for each image collection.
Optional Query Parameters
limit String 2 Specifies maximum number image collections to retrieve.

Status 200 application/json

Response Body:

{
    "itemKind": "IMAGECOLLECTIONHISTORY",
    "items": [
        {
            "id": "product-1",
            "user": "janedoe",
            "lastModifiedTimestamp": 1509418397300,
            "definition": {
                "version": 1,
                "items": [
                    {
                        "type": "image",
                        "url": "http://url.com/img1.jpg",
                        "mime": "image/jpeg"
                    },
                    {
                        "type": "image",
                        "url": "http://url.com/img2.jpg",
                        "mime": "image/jpeg"
                    }
                ]
            }
        },
        {
            "id": "product-1",
            "user": "johndoe",
            "lastModifiedTimestamp": 1509418397284,
            "definition": {
                "version": 1,
                "items": [
                    {
                        "type": "image",
                        "url": "http://url-bad.com/img1.jpg",
                        "mime": "image/jpeg"
                    },
                    {
                        "type": "image",
                        "url": "http://url-bad.com/img2.jpg",
                        "mime": "image/jpeg"
                    }
                ]
            }
        }
    ],
    "totalItems": 2
}
  1. Run the List Image Collections operation and store the imageCollectionId.

  2. If you want to specify the number of results to return, use the limit query parameter. If you want 10 results, add ?limit=10 to the endpoint.

  3. Make a GET request to /imaging/v0/imagecollections/{imageCollectionId}/history{?limit}.

The response includes the ImageCollection object.


Last modified: 1/30/2018