Images

Points of note

• Images are displayed prominently on an advert’s page. An advert can have up to 20 images. Images can also be assigned to individual advert variants.
• Images on adverts and variants can also include alt text content.
• Images are returned to the API consumer as a URL. These URLs can be used to retrieve the image for further processing / caching into a Digital Asset Management (DAM) system or similar.

Listing an advert or variant’s images

Request

GET /api/v2/client/adverts/1/images

OR

GET /api/v2/client/variants/1/images

Response

{
  "data": [
    {
      "id": "dea995bf53594ef2a754b7b14cd49e87",
      "type": "images",
      "attributes": {
        "url": "/dbimages/bike/fn_large/1/1/Cypress-DX.jpg",
        "alt": "alt text description of image"
      }
    }
  ]
}

Showing a single image

This endpoint allows you to request an image at a specific position within the advert or variant’s list of images. The example request here shows how to get the first image. Numbers up to 20 are supported.

Request

GET /api/v2/client/adverts/1/images/1

OR

GET /api/v2/client/variants/1/images/1

Response

{
  "data": {
    "id": "dea995bf53594ef2a754b7b14cd49e87",
    "type": "images",
    "attributes": {
      "url": "/dbimages/bike/fn_large/1/1/Cypress-DX.jpg",
      "alt": "alt text description of image"
    }
  }
}

Adding an image

This endpoint allows you to add up to 20 images to an advert or variant. For image uploads you will need to set the Content-Type to be multipart/form-data.

Points to note about supplying images:

• Image formats supported: PNG, GIF, JPG & JPEG
• File size lower than 32Mb
• Image urls must be resolvable by the Marketplacer app so:
  • They must be publicly accessible
  • If they are protected by a Web Application Firewall (WAF), rules will need to be in place to permit Marketplacer to retrieve
  • They must be resolvable in under 5s otherwise HTTP 422 response may be issued by the Marketplacer V2 API

Request

POST /api/v2/client/adverts/1/images

OR

POST /api/v2/client/variants/1/images

Input

Either image or image_url is required. If both are supplied, an error will be returned.

Here’s a curl example:

curl -i -H 'Authorization: Bearer 471dfba...' \
  -H 'Content-Type: multipart/form-data' \
  -F image=@bike.jpg \
  -F alt='alt text description of image' \
  -X POST \
  https://bikeexchange.com.au/api/v2/client/adverts/1/images

or

curl -i -H 'Authorization: Bearer 471dfba...' \
  -F image_url=https://my.site/images/my_image.jpg \
  -F alt='alt text description of image' \
  -X POST \
  https://bikeexchange.com.au/api/v2/client/adverts/1/images

Response

{
  "data": {
    "id": "dea995bf53594ef2a754b7b14cd49e87",
    "type": "images",
    "attributes": {
      "url": "/dbimages/bike/fn_large/1/1/Cypress-DX.jpg",
      "alt": "alt text description of image"
    }
  }
}

Response (422)

If the destination of the image url is not available for whatever reason. you can expect to receive a 422 Unprocessable Entity http response.

{
  "errors": [
    {
      "title": "Unable to fetch image",
      "detail": "Unable to process the image url: Unable to retrieve attachment: https://badurl.com/corrupt.jp",
      "id": null,
      "href": null,
      "code": 422,
      "source": null,
      "status": "server_error"
    }
  ]
}

Updating an image

To update an image, you must first know its position within the list of images returned from the listing images endpoint.

Request

PUT /api/v2/client/adverts/1/images/1

OR

PUT /api/v2/client/variants/1/images/1

Input

Either image or image_url is required. If both are supplied, an error will be returned.

Here’s a curl example:

curl -i -H 'Authorization: Bearer 471dfba...' \
  -H 'Content-Type: multipart/form-data' \
  -F image=@bike.jpg \
  -F alt='alt text description of image' \
  -X PUT \
  https://bikeexchange.com.au/api/v2/client/adverts/1/images/1

Response

{
  "data": {
    "id": "dea995bf53594ef2a754b7b14cd49e87",
    "type": "images",
    "attributes": {
      "url": "/dbimages/bike/fn_large/1/1/Cypress-DX.jpg",
      "alt": "alt text description of image"
    }
  }
}

Deleting an image

To update an image, you must first know its position within the list of images returned from the listing images endpoint.

Request

DELETE /api/v2/client/adverts/1/images/1

OR

DELETE /api/v2/client/variants/1/images/1

Response

Note: The subsequent images will move up in position. To delete all the images you will need to request DELETE /api/v2/client/adverts/1/images/1 4 times.