Introduction

The Files API allows to manipulate images of Offers, Offers
and Rewards.

File model

Every file attached to some entity (Offer, Reward, Offer Collection) follows the file schema and is defined like this:

Definition

Key	Type	Description
url	URL	Link to the file
width	integer	Image width
height	integer	Image height
kind	string	File kind identifier (e.x. `offer_default`), see Standard file kinds
size_type	string	e.x. `base`, see: File sizes

File schema

File schema defines a list of files kinds available in the Loyalty club.
Each file kind is also available in multiple sizes.

The schema may get retrieved with Files> Get schema endpoint.

Example

{
  "files_kinds": [
    {
      "identifier": "collection_cover_default",
      "type": "IMAGE",
      "ratio": "2:1",
      "sizes": [
        {
          "identifier": "base",
          "min_width": 600,
          "min_height": 300,
          "max_width": 600,
          "max_height": 300
        },
        {
          "identifier": "thumbnail",
          "min_width": 300,
          "min_height": 150,
          "max_width": 300,
          "max_height": 150
        },
        {
          "identifier": "original",
          "min_width": 600,
          "min_height": 300,
          "max_width": null,
          "max_height": null
        }
      ]
    },
    {
      "identifier": "offer_default",
      "type": "IMAGE",
      "ratio": "3:4",
      "sizes": [
        {
          "identifier": "base",
          "min_width": 600,
          "min_height": 800,
          "max_width": 600,
          "max_height": 800
        },
        {
          "identifier": "thumbnail",
          "min_width": 225,
          "min_height": 300,
          "max_width": 225,
          "max_height": 300
        },
        {
          "identifier": "original",
          "min_width": 600,
          "min_height": 800,
          "max_width": null,
          "max_height": null
        }
      ]
    },
    {
      "identifier": "reward_default",
      "type": "IMAGE",
      "ratio": "3:4",
      "sizes": [
        {
          "identifier": "base",
          "min_width": 600,
          "min_height": 800,
          "max_width": 600,
          "max_height": 800
        },
        {
          "identifier": "thumbnail",
          "min_width": 225,
          "min_height": 300,
          "max_width": 225,
          "max_height": 300
        },
        {
          "identifier": "original",
          "min_width": 600,
          "min_height": 800,
          "max_width": null,
          "max_height": null
        }
      ]
    },
    {
      "identifier": "example_without_ratio",
      "type": "IMAGE",
      "ratio": null,
      "sizes": [
        {
          "identifier": "base",
          "min_width": 600,
          "min_height": 600,
          "max_width": null,
          "max_height": null
        },
        {
          "identifier": "thumbnail",
          "min_width": null,
          "min_height": null,
          "max_width": 300,
          "max_height": 300
        },
        {
          "identifier": "original",
          "min_width": 600,
          "min_height": 600,
          "max_width": null,
          "max_height": null
        }
      ]
    }
  ]
}

File kind model

Key	Type	Description
identifier	string	See: Standard file kinds
type	string	Currently, only `IMAGE` (MIME: `image/gif`, `image/jpeg`, `image/png`) is supported
ratio	string	Describes ratio of an image. See: Ratio (optional)
sizes	Object[]	See: File sizes
sizes[]['identifier']	string
sizes[]['min_width']	integer	(optional)
sizes[]['min_height']	integer	(optional)
sizes[]['max_width']	integer	(optional)
sizes[]['max_height']	integer	(optional)

Standard file kinds

There are some standard file kinds, their size definitions differ among Loyalty Clubs.

Identifier	Description
`collection_cover_default`	Cover for Offer collections
`offer_default`	Default Offer image
`reward_default`	Default Reward image

Ratio

Images may have fixed proportions ratio which is represented as a string: "<width>:<height>"

File sizes

Every file has at least three file sizes available:

`base`

Actual file size. Currently all file kinds have this size with fixed proportions (so min_* == max_*) that match the ratio.

`thumbnail`

Rescaled version of base size. Currently, rescaling always works this way:

pick the higher dimension of file

shrink the image so:

the higher dimension gets shrunk to 300px

the lower dimensions gets shrunk so the image keeps the original ratio

Example:

File with resolution 600x800 gets shrunk down to 225x300

File with resolution 800x600 gets shrunk down to 300x225

File with resolution 400x300 gets shrunk down to 300x225

File with resolution 400x200 gets shrunk down to 300x150

File with resolution 300x250 is not shrunk down

`original`

Original file that that has been uploaded and used for generating other file sizes.

Currently, we require all original files to have proper ratios and minimum sizes of at least the base size.
Because of that, you can expect them to have min_height and min_width that match the base size,
but they never have max_width or max_height defined.

File cropping

crop_to param interpretation may be visualized like this:


                           x_top_left     x_bottom_right
                    |-------------------------------------
                    | ..........................
                    | ..........................
     y_top_left     | .....*---------------.....
                    | .....|..............|.....
                    | .....|..............|.....
                    | .....|..............|....
     y_bottom_right | .....---------------*.....
                    | ..........................
                    |

When file is uploaded and it's too large to match the required base size, it may get cropped.
This can be achieved by providing cropping param (crop_to).

The param has following syntax: x_top_left,y_top_left,x_bottom_right,y_bottom_right and represents boundaries of a cropping area.

When uploaded file is too large and crop_to param is not provided, the file will be automatically cropped with gravity set in center of image.

Example

The kind's base size is 400x200px and the uploaded file is 1000x1000px.

With crop_to="0,250,1000,750", a rectangle of "1000x500" size will be cropped, with 250px left offset.
The file will be then also resized to 400x200.

Uploaded instances projections

When file is uploaded, only original file is physically processed and stored. base and other versions are processed asynchronously.
So, the responses returned on upload contains only "projected" info about files.

Key	Type	Description
size_type	string
url	string	An URL the file be available on after it gets processed.
min_width	integer
max_width	integer
min_height	integer
max_height	integer

File model#

Definition#

File schema#

Example#

File kind model#

Standard file kinds#

Ratio#

File sizes#

base#

thumbnail#

original#

File cropping#

Uploaded instances projections#

File model

Definition

File schema

Example

File kind model

Standard file kinds

Ratio

File sizes

`base`

`thumbnail`

`original`

File cropping

Uploaded instances projections