Item

#ItemController

Overview

• Description

  • Item JSON object

  • JSON Fields

  • CSV fields

• GET /

• GET /:id

• PUT /:id (json)

• PUT /:id (multipart)

• DELETE /:id/:assetType

• GET /:id/topImage

• GET /:id/perspectiveImage

• GET /:id/perspectiveImageHD

• GET /:id/threeDimensionalAssets

• POST /:id/renderings

• POST /:id/3d-exports

• POST /:id/conversions

Description

Path /v2/items

Handles all requests regarding items: creating, updating, deleting.

Item object

An example for a item json object.

{
    "width": 350,
    "height": 2250,
    "depth": 340,
    "displayedWidth": 300,
    "displayedHeight": 2200,
    "displayedDepth": 310,
    "perspectiveImage": "https://url-of-perspectiveImage",
    "perspectiveImageHD": "https://url-of-perspectiveImageHD",
    "topImage": "https://url-of-topImage",
    "assets": {
        "usdz":{
            "format":"usdz",
            "url":"https://uploads.roomle.com/somePath/to/some/usdz/file.usdz"},
        "glb":{
            "format":"glb",
            "url":"https://uploads.roomle.com/somePath/to/some/glb/file.glb"}
    },
    "configuration": "configuration as JSON",
    "hidden": false,
    "visibilityStatus": 0,
    "created": "2016-04-11T14:34:14.000Z",
    "manufacturerSKU": "manuSKU",
    "updated": "2016-04-12T09:17:16.000Z",
    "type": "storage",
    "detailType": "cabinet",
    "flipable": false,
    "scaleable": false,
    "colorable": false,
    "layer": 30,
    "orderable": false,
    "requestable": true,
    "retailPriceAllowed": false,
    "label": "USM TV Lowboard ",
    "language": "en",
    "catalog": "usm",
    "id": "usm:TVLowboard",
    "tags": ["living", "usm_root"],
    "affiliateIds": ["affiliate1", "affiliate2"],
    "links": {
        "tags": "/items/usm:TVLowboard/tags",
        "additionalContents": "/items/usm:TVLowboard/additionalContents",
        "similarItems": "/items/usm:TVLowboard/similarItems",
        "perfectFit": "/items/usm:TVLowboard/perfectFit"
    },
    "attributes": [{
        "key": "material",
        "value": "testMaterial",
        "label": "testLabel"
    }],
    "basecolor": "aabbcc",
    "elementType": "1",
    "assetProcessings": [{
      "id": "anyStringId",
      "type": 0,
      "status": 10,
      "sourceUrl": "link/to/source.zip"
    }],
    "translations": [{
      "language": "en",
      "label": "labelEN"
    }],
    "version": 3
}

Responses are usually wrapped in a meta object, which contains additional information about the response and may contain a single item or a list of items.

{
    "item": 
        {itemObject},
    "items": [
        {itemObject1},
        {itemObject2},
        ...
    ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": 2,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}

JSON Fields

• width

• height

• depth

• displayedWidth

• displayedHeight

• displayedDepth

• perspectiveImage

• perspectiveImageHD

• topImage

• assets : the known 3dAssets for this item.

• configuration

• hidden - deprecated - superseded by visibilityStatus

• visibilityStatus : possible values

  • 0 : SHOWN (visible everywhere)

  • 1 : SHOWN_IN_CMS (visible only in cms context)

  • 2 : ARCHIVED (hidden everywhere)

• created

• manufacturerSKU

• updated

• type

• detailType

• flipable

• scaleable

• colorable

• layer

• orderable

• requestable

• retailPriceAllowed

• label

• language

• catalog

• id

• tags

• affiliateIds

• links

• attributes

• basecolor

• version

CSV fields

• id: identifier of an item (Deprecated)

• item_id : identifier of an item

• Translations can be multiple, we always return all the available translations in the form of multiple column pairs. If no translations are available, we insert in the CSV reference columns label_en and description_en.

  • label_{languageCode}: languageCode in ISO standard can be "en" or "de" for example and will be the current value of this language in the ItemTranslation.

  • description_{languageCode}: languageCode in ISO standard can be "en" or "de" for example and will be the current value of this language in the ItemTranslation.

• type: for example "seating" or "table"

• detailType: for example "sofa", "chair" or "table"

• width: width of the item in millimeters

• depth: depth of the item in millimeters

• height: height of the item in millimeters

• layer: can be an integer or null, if there is no value for this field

• sort: can be an integer or null, if there is no value for this field

• scaleable: indicates if the item is scalable or not

• flipable: indicates if the item can be flipped or not

• colorable: indicates if the item can be colored or not

• hidden: indicates if the item is hidden

• manufacturerSKU:

• tag_ids: all tag ids separated by ' ' (whitespace)

• configuration: the configuration of the item

• visibilityStatus :

  • 0 : SHOWN (visible everywhere)

  • 1 : SHOWN_IN_CMS (visible only in cms context)

  • 2 : ARCHIVED (hidden everywhere)

API Reference

GET /

Generates: json

Query item data based on given filters. If no filter is added by query parameters, all visible items for the requested user will be returned.

query-param:

• deltaSince: has to be a date string with timezone. This string has to match following example 2016-06-01T07:54:07.000Z. Only if given date string is matching this format, the response will be reduced to only updated items after given date.

Filter:

Each bullet point describes an available filter, where each secondary bullet point/s names the query parameter, which has to be added to the request in order to execute that filter correctly. If requirements for a filter are not met, then the request will behave like no filter was added and therefore will return all visible items.

• all items for one catalog

  • catalog

• all items for many catalogs

  • catalog[]

• all items which are visible to the requested user and match types

  • types[]

• specific items per id

  • ids[]

• perfect fit items per item ids

  • perfectFitItemIds[]

• perfect fit items per component ids

  • perfectFitComponentIds[]

• similar items

  • type

  • detailType

  • color

  • width

  • depth

  • height

Response:

Item objects are described in Section Item JSON Object

{
    "items": [
        itemObjects1,
        itemObject2,
        ...
    ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": 2,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}

GET /:id

Gets an existing Item.

Accepts: application/json

Generates: application/json

Response (200 OK): Item JSON Object

PUT /:id (json)

Updates an existing Item.

Accepts: application/json

Generates: application/json

Response (200 OK): Updated Item JSON Object

PUT /:id (multipart)

updates assets on an item

Accepts: multipart-formdata

Generates: application/json

parameters:

• the data, either as file or as URL. if both are provided, an error is returned

  • file : datafile to be uploaded

  • fileUrl: the publicly available url to the datafile

• type: type of the asset

possible types are

• "perspectiveImage"

• "perspectiveImageHD"

• "topImage"

• "glb_preview"

• "src"

Response (200 OK): Item JSON Object

For more information on the assets, please check ElementAssets

DELETE /:id/:assetType

deletes assets on an item

possible types are images:

• "perspectiveImage"

• "perspectiveImageHD"

• "topImage" 3d data:

• "glb_preview"

Response (204 NO CONTENT): deleted

For more information on the assets, please check ElementAssets

GET /:id/topImage

returns a temporary redirect (307) to the URL of the topImage for this item

GET /:id/perspectiveImage

returns a temporary redirect (307) to the URL of the perspectiveImage for this item

GET /:id/perspectiveImageHD

returns a temporary redirect (307) to the URL of the perspectiveImageHD for this item

Uploading 3D Assets

You can upload 3D Assets for an item which will then be processed for realtime usage within the Roomle platform. If processed successfully, the dimensions of the 3D Asset will be taken as dimensions for the object, overriding any previously existing dimensions.

Asset Processing JSON object

An example for an asset processing object.

Type	Description
0	item

Status	Description
0	DAP received job
10	DAP is processing this job
100	DAP has successfully processed this job
-1	DAP had some kind of error while processing

{
	"id": "anyStringId",
	"type": 0,
	"status": 10,
	"sourceUrl": "link/to/source.zip"
}

GET /:id/threeDimensionalAssets

Generates: json

Returns all asset processing statuses for requested item

Response: Asset Processing objects are described in Section Asset Processing JSON Object

{
    "assetProcessings": [
        assetProcessingObjects1,   
        assetProcessingObjects2,
        ...
    ],
    "meta": {
        "total": 2,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}

POST /:id/threeDimensionalAssets - DEPRECATED

since 2.41.3 - May 2024

use PUT /:id (multipart) instead

Requestinga a 3D Asset processing

POST /:id/renderings

Creating a new asset processing rendering job (DAP-job) for requested item.

Accepts: multipart-formdata

Generates: json

path-parameters:

• id : item id

form-parameters: The form parameter body for rendering require the settings property to be present and views field of this property to be non-empty.

• settings: contains all settings for import/render/export

{
    "light_preset": "default",
    "quality": "default",
    "views": [
        {
            "resolution_height": 1080,
            "resolution_width": 1920,
            "view_type": "perspective"
        },
        {
            "pixel_per_meter": 400,
            "view_type": "ortho_top"
        },
        {
            "camera_yaw": 0.0,
            "resolution_height": 1080,
            "resolution_width": 1920,
            "steps": 18,
            "view_type": "turntable"
        }
    ]
}

POST /:id/3d-exports

Creating a new asset processing 3d-exports job (DAP-job) for requested item.

Accepts: multipart-formdata

Generates: json

path-parameters: -id : item id

form-parameters: The form parameter body for 3d-exports require the settings property to be present and the export field of this property to be non-empty.

• settings: contains all settings for import/render/export.

{
    "formats": [
        {
            "file_format": "blend",
            "pack_external_data": true
        }
    ]
}

POST /:id/assets - DEPRECATED

since 2.41.3 - May 2024

use PUT /:id (multipart) instead

POST /:id/conversions

Creating a new asset processing conversion job (DAP-job) targeting the item.

Accepts: multipart-formdata

Generates: json

path-parameters:

• id : String - combinedId of the item where the results of the conversion will be saved, must be already created

form-parameters:

• sourceId : String - combined id of the item that is the source of the conversion

• type : String - identifier of the conversion type

• settings: contains all settings for import/render/export/convert.

Settings json example:

{
    "target_id": "catalogId:targetItemId"
}

Conversion types:

• 'static-to-configurable' : This conversion takes the source static item and converts it into a configurable item by creating materials, textures, meshes and components. The resulting component is then set as the target items root component, to achieve an immediately usable configurable item.