Photos Collection
API Methods to work with Photos
Photo is entity to represent photo associated with Property and Room Type (optional).
Right now, Create Photo API doesn't support upload files, but we have this feature at our Roadmap. Please, use our application UI to upload photos, this way provide better User Experience for you and allow you use all features associated with Photo transformations.
Photos List
Retrieve list of Photos associated with user Properties.
Request:
Returns
Success
Method can return a Success result with 200 OK
HTTP Code if operation is successful. Will contain a list of Photo objects in the answer.
Unauthorised Error
Method can return a Unauthorised Error result with 401 Unauthorized
HTTP Code if wrong Bearer Token provided.
Get Photo by ID
Retrieve specific Photo by ID.
Request:
Returns
Success
Method can return a Success result with 200 OK
HTTP Code if operation is successful. Will contain a Photo object in the answer.
Unauthorised Error
Method can return a Unauthorised Error result with 401 Unauthorized
HTTP Code if wrong Bearer Token provided or User not have access to requested Photo.
Not Found Error
Method can return a Not Found Error result with 404 Not Found
HTTP Code if Photo with provided ID is not present at system.
Create Photo
Create new Photo.
Request:
Query body (JSON):
Fields
property_id [required]
String with valid UUID of Property object what you would like to associate with created Photo.
url [required]
Valid URL address of Photo image.
room_type_id [optional]
String with valid UUID of Room Type object what you would like to associate with created Photo.
If room_type_id
is null
, Photo will be associated only with Property.
kind [optional]
One of three possible values: photo
, ad
(advertising), menu
(restaurant menu photo).
By default value kind will be equal to photo
.
author [optional]
Name of photo author.
description [optional]
Text with Photo description.
position [optional]
Any positive integer number.
This field represent Photo position at list of Property or Room Type Photos. Photo with position equal to 0 is used as Cover Photo.
Position should be uniq per property_id
and room_type_id
combination.
Returns
Success
Method can return a Success result with 201 Created
HTTP Code if operation is successful. Will contain a Photo object in the answer.
Unauthorised Error
Method can return a Unauthorised Error result with 401 Unauthorized
HTTP Code if wrong Bearer Token provided.
Validation Error
Method can return a Validation Error result with 422 Unprocessable Entity
HTTP Code if any validation rule is failed.
Update Photo
Update Photo.
Request:
Query body (JSON):
Fields
This method use same fields as Create Photo method.
Returns
Success
Method can return a Success result with 200 OK
HTTP Code if operation is successful. Will contain a Photo object in the answer.
Unauthorised Error
Method can return a Unauthorised Error result with 401 Unauthorized
HTTP Code if wrong Bearer Token provided.
Not Found Error
Method can return a Not Found Error result with 404 Not Found
HTTP Code if Photo with provided ID is not present at system.
Validation Error
Method can return a Validation Error result with 422 Unprocessable Entity
HTTP Code if any validation rule is failed.
Remove Photo
Remove Photo.
Request:
Returns
Success
Method can return a Success result with 200 OK
HTTP Code if operation is successful. Will contain a Meta object with message in the answer.
Unauthorised Error
Method can return a Unauthorised Error result with 401 Unauthorized
HTTP Code if wrong Bearer Token provided.
Not Found Error
Method can return a Not Found Error result with 404 Not Found
HTTP Code if Photo with provided ID is not present at system.
Batch operations
API methods to create or update Property or Room Type have implementation of Photo batch operations.
To create Property with Photos, you can pass list of Photo arguments as value into content.photos
key of affected object.
Batch operations support logic to create new Photo entity associated with parent object, update existed photos or drop it.
To update Photo at batch operation, you must provide photo with it ID.
To drop Photo at batch operation, you can pass additional optional key: is_removed
with value equal to true
at Photo object what are you like to remove.
Photo Transformations
Concept
Photo Transformations can help you enhance images, optimize them, implement responsive images or art direction. In any of the listed cases, you will either go with modifying original images or making several versions of an original. All that can be done on-the-fly by including the respective URL directives in CDN URLs related to photos. For example,
We support many input image formats, while the processed outputs will always be set to one of these three: PNG
, JPEG
or WebP
.
Resize Image Proportionally, preview
preview
-/preview/
-/preview/:two_dimensions/
Reduces an image proportionally for it to fit into the given dimensions in pixels. If dimensions are not specified, we use the default values of 2048x2048
pixels.
Resize Image, resize
resize
/resize/:one_or_two_dimensions/
Resizes an image to fit into the specified dimensions. With just a single linear dimension specified, preserves your original aspect ratio and resizes an image along one of its axes.
Crop Image, crop
crop
-/crop/:two_dimensions/
-/crop/:two_dimensions/:two_coords/
-/crop/:two_dimensions/center/
Crops an image using specified dimensions and offsets. If no offset values are passed into the operation, the top-left image corner is used by default.
If given dimensions are greater than the ones of the original image, the image is rendered inside a color-filled box. The color of that box can be changed via the setfill
operation.
Downscale and Crop Image, scale_crop
scale_crop
-/scale_crop/:two_dimensions/
-/scale_crop/:two_dimensions/:type/
-/scale_crop/:two_dimensions/:offsets/
When :type
is not specified.
Scales down an image until one of its dimensions gets equal to some of the specified ones; the rest is cropped. This proves useful when your want to fit as much of your image as possible into a box. Let us compare the two resizing methods:
When :type
is set to smart
.
Switching the crop type to smart enables the content-aware mechanics: detecting faces and other visually important objects or areas in images.
Example:
Set resize
Behavior, stretch
resize
Behavior, stretch
-/stretch/:mode/
Sets the resize
behavior when a source image is smaller than the resulting dimensions. The following modes can apply:
on
— stretches an image up, the default option.off
— forbids stretching an image along any dimension that exceeds image size along any of its axes.fill
— does not stretch an image, the color-filled frame is rendered around instead, the default fill color is used.
Set Fill Color, setfill
setfill
-/setfill/:color/
Sets the fill color used with crop
, stretch
or when converting an alpha channel enabled image to JPEG. The operation uses hexadecimal notation to define colors.
Changing Image Format, format
format
-/format/:format/
Converts an image to one of the following formats:
jpeg
— JPEG is a lossy image format (good compression, good for photos). JPEG doesn’t support an alpha channel, hence you can use thesetfill
operation that sets a background color. All browsers support JPEG.png
— PNG is a lossless format (good compression only for graphics) with alpha channel support. Supported by all browsers.webp
— WebP is a modern image format that supports alpha channel and lossy compression. The format is good for all kinds of images but supported by a limited number of browsers.auto
— the image format used for content delivery is set according to the presence of an alpha channel in your input and capabilities of a client.
Technically, the default behavior of auto
is about always trying to deliver WebP images based on checking the Accept
header.
Beside using -/format/auto/
, there is another way to control which image format is delivered to a client. In HTML 5, you can force the browser to automatically choose a WebP image version over others. This is done by using <picture>
. Simply, wrap your <img>
element with <picture>
and add <source>
having its type set to type="image/webp"
. Compatible browsers will then automatically load the WebP image version; others will take either JPEG or PNG.
Changing Image Quality, quality
quality
-/quality/:value/
Sets the level of image quality that affects file sizes and hence loading speeds and volumes of generated traffic. quality
works with JPEG and WebP images.
When your input and output are both JPEGs and no destructive operations are applied, your output image quality is limited to the initial input quality: when you upload a highly compressed image, you can use the normal
setting or go even higher, but it will not affect neither your compression settings nor file size.
normal
— the default setting, suits most cases.better
— can be used to render relatively small and detailed previews. ≈125% file size compared tonormal
.best
— useful for hi-res images, when you want to get perfect quality without paying much attention to file sizes. ≈170% file size.lighter
— useful when applied to relatively large images to save traffic without significant losses in quality. ≈80% file size.lightest
— useful for retina resolutions, when you don’t have to worry about the quality of each pixel. ≈50% file size.
Implementing Multi-Scan Images, progressive
progressive
-/progressive/yes/
-/progressive/no/
Returns a progressive image. In progressive images, data are compressed in multiple passes of progressively higher detail. This is ideal for large images that will be displayed while downloading over a slow connection allowing a reasonable preview after receiving only a portion of the data. The operation does not affect non-JPEG images; does not force image formats to JPEG
.
Last updated