Agenda photo

Contains the photos of ads

Sub-agendas overview

Name	Machine name	WRITE
Resize	`resize`	NO
Sort	`sort`	YES

Agenda features

Name	Options
Supported methods	`GET`, `PUT`/`POST`, `DELETE`
Support for detail levels	✘
Support for filtering	✘
Support for full-text search	✘
Support for pagination	✘
Support for sorting	✘
Support for external identifiers	✔
Support for `schemas`	https://api.tipmoto.com/schemas/photo-{export\|import}.{xsd\|rng}
Support for `?fail-on-warning`	✘
Support for dry-run	✘
Returns `location`	✘

Agenda elements

Machine name	Name	Type	Information	rw	P
`@forceupdate`	Forced update	`select`	Possible values `true` Yes `false` No If set, an update is always forced when the photo is submitted by URL. We recommend not sending it by default, but using it only when you know the photo has changed.
`@modify`	Photo adjustment	`select`	Used only when importing. Possible values: `trim` = if the photo has a border, it is cropped automatically
`id`	Photo ID	`integer`	Photo ID within the given ad
`url`	URL	`string 255`	URL of the photo	✔	✔
`main`	Main photo	`select`	This is the main photo, which is shown in the preview; the main photo is always at position 1 Possible values: `1` or `true` Yes – the photo moves to position 1, the others keep their relative order `0` or `false` No – on its own it changes nothing When reading always `0` or `1`. An invalid value is ignored and the response contains a `warning`. See Photo order and main photo.	✔
`sortOrder`	Photo order	`integer`	Position of the photo in the ad gallery, `1` = main photo. When reading, it is the position at which the website shows the photo. When writing, an absolute position: the photo is placed at the given position and the other photos fill the remaining positions in their existing order; a number greater than the number of photos means the end of the gallery. A value other than a whole number from 1 returns error `406`, as does a `sortOrder` other than `1` together with `main` = `1` or `1` together with `main` = `0`.	✔
`stamp`	Photo stamp	`string 128`	A stamp identifying the photo On export the value is in the `datetime` format, i.e. `YYYY-MM-DD HH:MM:SS` On import it can be any value; if the stamp changes, the photo is updated. We recommend using a datetime, file size, file hash, etc. In this agenda the content of the photo is overwritten under the same ID and the photo stays in its position. When a photo is replaced via `stamp` in the ad import (`photos`), on the other hand, it gets a new ID.	✔
`width`	Photo width in px	`integer`	Read-only value
`height`	Photo height in px	`integer`	Read-only value
`urlApi`	URL via API	`string 255`	If the photo was imported via the API, the photo `url` is stored here. Read-only value
`stampApi`	stamp via API	`string 255`	If the photo was imported via the API, the photo `stamp` is stored here. Read-only value
`resize`	Sub-agenda resize		Links to the sub-agenda `resize`, which allows resizing the image
`content`	Photo content	`text`	Instead of a URL, a photo can be uploaded via the API by sending the content of the photo file in the `content` tag. We do not recommend this solution, because processing of large photos may fail. The raw data must be encoded with Base64. When sending raw photos, PUT with RAW-DATA is better

rw = writable
P = required element
~~S = the element can be used for filtering and sorting~~
~~➀ = included in detail level id~~
~~➁ = included in detail level summary~~

PUT with raw photo data

When you use the URL parameter ?raw-data=true, you can send the source data of the photo directly in the PUT request.

Supported photo formats

You can send a photo in any of these formats – this applies equally to url, content (Base64) and raw-data:

JPEG
PNG
GIF
BMP
TIFF
WebP

We always convert the photo to our own format (JPG and WebP) and process it the same way regardless of the format it arrived in. Specifically:

a photo larger than 1600×1200 is downsized,
transparency (PNG, GIF, WebP) is replaced with white,
for an animated GIF or WebP and for a multi-page TIFF, the first frame is used.

The format is determined by the file content, not by the extension in the URL – so you can serve the photo even at an address without an extension or with the .php extension. A format outside the list above is rejected and the response contains the error Unsupported image format. Allowed formats: JPEG, PNG, GIF, BMP, TIFF, WebP.

Photo order and main photo

You change the order and the main photo of one photo with the elements sortOrder and main. The rules are the same as in the ad import and are described in detail in Order and main photo:

The main photo is always at position 1. main = 1 moves the photo to position 1 and the other photos keep their relative order; main = 0 on its own changes nothing.
sortOrder is an absolute position: the photo is placed at the given position and the other photos fill the remaining positions in their existing order. A number greater than the number of photos means the end of the gallery.
Changing only the order or the main photo: a PUT to /photo/{id} (or with id in the body) with only sortOrder and/or main, without url and content, is enough. Nothing is downloaded and the content of the photo does not change. The same applies when you send an unchanged url and stamp together with sortOrder or main.
A new photo without sortOrder and main is added at the end of the gallery. The first photo uploaded to an ad that has no photos yet always becomes the main photo.
Replacing the content of a photo (url with a changed stamp, forceupdate, content or raw-data for an existing photo) overwrites the content under the same ID and the photo stays in its position. Note that the ad import (photos) behaves differently: there a photo replaced via stamp gets a new ID.
After a photo is added or deleted, the order is normalised: positions run continuously from 1 and there is exactly one main photo.

Error 406 is returned for: a sortOrder that is not a whole number from 1; main = 1 together with a sortOrder other than 1, or main = 0 together with sortOrder = 1; a change of order without a photo ID (neither in the URL nor in id). In that case nothing changes.
An invalid value of main (other than 1/true/0/false) is ignored and the response contains a notice in result/warnings. The response to PUT/POST and DELETE contains result/warnings and result/infos if there are any.

To change the order of several photos at once, use the sub-agenda photo/sort.