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.
Retrieve list of Photos associated with user Properties.
Request
Success Response
Error Response
Request:
GET https://staging.channex.io/api/v1/photos
Success Response Example
Status Code:
200 OK{
"data": [
{
"attributes": {
"author": null,
"description": null,
"id": "ae75d43e-21c5-46b6-a593-5046791f7841",
"kind": "ad",
"position": 0,
"property_id": "52397a6e-c330-44f4-a293-47042d3a3607",
"room_type_id": null,
"url": "https://img.channex.io/312fa6cb-8151-409b-b612-773e271a76df/"
},
"id": "ae75d43e-21c5-46b6-a593-5046791f7841",
"type": "photo"
}
],
"meta": {}
}
Unauthorised Error Response
Status Code:
401 Unauthorized{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}
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. Retrieve specific Photo by ID.
Request
Success Response
Error Response
Request:
GET https://staging.channex.io/api/v1/photos/:id
Success Response Example
Status Code:
200 OK{
"data": {
"attributes": {
"author": null,
"description": null,
"id": "ae75d43e-21c5-46b6-a593-5046791f7841",
"kind": "ad",
"position": 0,
"property_id": "52397a6e-c330-44f4-a293-47042d3a3607",
"room_type_id": null,
"url": "https://img.channex.io/312fa6cb-8151-409b-b612-773e271a76df/"
},
"id": "ae75d43e-21c5-46b6-a593-5046791f7841",
"type": "photo"
}
}
Unauthorised Error Response
Status Code:
401 Unauthorized{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}
Not Found Error
Status Code:
404 Not Found{
"errors": {
"code": "not_found",
"title": "Resouce Not Found"
}
}
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 new Photo.
Request
Success Response
Error Response
Request:
POST https://staging.channex.io/api/v1/photos
Query body (JSON):
{
"photo": {
"author": "Author Name",
"description": "Room View",
"kind": "photo",
"position": 0,
"url": "https://img.channex.io/af08bc1d-8074-476c-bdb7-cec931edaf6a/",
"property_id": "52397a6e-c330-44f4-a293-47042d3a3607",
"room_type_id": null
}
}
Success Response Example
Status Code:
201 Created{
"data": {
"attributes": {
"author": "Author Name",
"description": "Room View",
"id": "656d8cab-beaa-45a3-8ddb-44684816edba",
"kind": "photo",
"position": 0,
"property_id": "52397a6e-c330-44f4-a293-47042d3a3607",
"room_type_id": null,
"url": "https://img.channex.io/af08bc1d-8074-476c-bdb7-cec931edaf6a/"
},
"id": "656d8cab-beaa-45a3-8ddb-44684816edba",
"type": "photo"
}
}
Unauthorised Error Response
Status Code:
401 Unauthorized{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}
Validation Error Response
Status Code:
422 Unprocessable Entity{
"errors": {
"code": "validation_error",
"title": "Validation Error",
"details": {
"url": [
"can't be blank"
]
}
}
}
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.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.
Request
Success Response
Error Response
Request:
PUT https://staging.channex.io/api/v1/photos/:id
Query body (JSON):
{
"photo": {
"author": "Author Name",
"description": "Room View",
"kind": "photo",
"position": 0,
"url": "https://img.channex.io/af08bc1d-8074-476c-bdb7-cec931edaf6a/",
"property_id": "52397a6e-c330-44f4-a293-47042d3a3607",
"room_type_id": null
}
}
Success Response Example
Status Code:
200 OK{
"data": {
"attributes": {
"author": "Author Name",
"description": "Room View",
"id": "656d8cab-beaa-45a3-8ddb-44684816edba",
"kind": "photo",
"position": 0,
"property_id": "52397a6e-c330-44f4-a293-47042d3a3607",
"room_type_id": null,
"url": "https://img.channex.io/af08bc1d-8074-476c-bdb7-cec931edaf6a/"
},
"id": "656d8cab-beaa-45a3-8ddb-44684816edba",
"type": "photo"
}
}
Unauthorised Error Response
Status Code:
401 Unauthorized{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}
Not Found Error
Status Code:
404 Not Found{
"errors": {
"code": "resource_not_found"
"title": "Resource Not Found"
}
}
Validation Error Response
Status Code:
422 Unprocessable Entity{
"errors": {
"code": "validation_error",
"title": "Validation Error",
"details": {
"url": [
"can't be blank"
]
}
}
}
This method use same fields as Create Photo method.
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.
Request
Success Response
Error Response
Request:
DELETE https://staging.channex.io/api/v1/photos/:id
Success Response Example
Status Code:
200 OK{
"meta": {
"message": "Success"
}
}
Unauthorised Error Response
Status Code:
401 Unauthorized{
"errors": {
"code": "unauthorized",
"title": "Unauthorized"
}
}
Not Found Error
Status Code:
404 Not Found{
"errors": {
"code": "resource_not_found"
"title": "Resource Not Found"
}
}
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 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 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,
https://img.channex.io/:uuid/-/resize/200x/
We support many input image formats, while the processed outputs will always be set to one of these three:
PNG, JPEG or WebP.-/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./:uuid/-/preview/
/:uuid/-/preview/300x500/
/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.
/:uuid/-/resize/200x200/
/:uuid/-/resize/200x/
/:uuid/-/resize/x200/
-/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.-/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:
-/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.
-/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.-/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 thesetfilloperation 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.<picture>
<source srcset="//img.channex.io/:uuid/:operations/-/format/webp/" type="image/webp"/>
<img src="//img.channex.io/:uuid/:operations/-/format/auto/"/>
</picture>
-/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.
-/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.
Baseline loading. |
Progressive loading. |
Last modified 3yr ago