Images

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.

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.