ItemController

Overview

Description

Path /v2/items

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

Item Object

An example for an 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": [
        <Item Object 1>,
        <Item Object 2>,
        ...
    ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": <number of items>,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}

JSON Fields

  • width

  • height

  • depth

  • displayedWidth

  • displayedHeight

  • displayedDepth

  • perspectiveImage

  • perspectiveImageHD

  • topImage

  • assets : the assets for this item

  • threeDimensionalAssetWeb - deprecated since 2.41.3 - superseded by assets

  • threeDimensionalAssetIOS - deprecated since 2.41.3 - superseded by assets

  • generic3dAsset - deprecated since 2.41.3 - superseded by assets

  • configuration

  • hidden - deprecated since 2.88.0 - 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

  • tags_collection - deprecated since 2.88.0 - superseded by tags

  • affiliateIds

  • links

  • attributes

  • basecolor

  • elementType

  • meta

  • rootComponentId

  • sort

  • generatedLabels

  • assetProcessings

  • translations

  • additionalInfos

  • version

CSV fields

  • id: identifier of an item - deprecated since 2.88.0 - use item_id instead

  • 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: deprecated since 2.88.0 - superseded by visibilityStatus

  • manufacturerSKU:

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

  • configuration: the configuration of the item

  • visibilityStatus : possible values

    • 0 : SHOWN (visible everywhere)

    • 1 : SHOWN_IN_CMS (visible only in cms context)

    • 2 : ARCHIVED (hidden everywhere)

API Reference

GET /

Generates: application/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 (200 OK): List of Item objects as described in Section Item Object

POST /

Creates a new item in the catalog provided in the body.

Accepts: application/json Generates: application/json

Body: Item Object

Response (201 CREATED): Item Object

GET /:id

Gets an existing Item.

Accepts: application/json

Generates: application/json

Response (200 OK): Item Object

PUT /:id (json)

Updates an existing Item.

Accepts: application/json

Generates: application/json

Response (200 OK): Updated Item 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"

  • "source"

Response (200 OK): Item JSON Object

For more information on the assets, please check ElementAssets

DELETE /:id/:assetType

Deletes an asset 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

Redirects to the top image of the specified item.

Response (307 TEMPORARY REDIRECT ): the URL of the topImage for this item

GET /:id/perspectiveImage

Redirects to the perspective image of the specified item.

Response (307 TEMPORARY REDIRECT ): the URL of the perspectiveImage for this item

GET /:id/perspectiveImageHD

Redirects to the high-definition perspective image of the specified item.

Response (307 TEMPORARY REDIRECT ): the URL of the perspectiveImageHD for this item

GET /:id/similarItems

Returns items similar to the specified item based on type, detailType, dimensions, and color.

Generates: application/json

Response (200 OK): List of Item JSON object

GET /:id/perfectFit

Returns items that have perfect fit relationships with the specified item.

Generates: application/json

Response (200 OK): List of Item JSON object

GET /:id/tags

Returns all tags assigned to the specified item.

Generates: application/json

Response (200 OK): List of Tag JSON object

GET /:id/additionalContents

Returns additional content associated with the specified item.

Generates: application/json

Response (200 OK): List of Additional content objects

GET /:id/tagConnections

Returns all tag connections for the specified item.

Note: Requires CMS context.

Generates: application/json

Response (200 OK): List of Tag connection objects

GET /:id/threeDimensionalAssets

Returns asset processing information for the specified item.

Generates: application/json

Response (200 OK): List of asset processing objects

GET /:id/3dAssets/:format/:dummyFileName

Downloads a 3D asset in the specified format for the item. The dummyFileName is ignored by the server and is only used in the URL to provide a meaningful filename when downloading the asset.

Generates: application/octet-stream

Query Parameters:

Name
Type
Comment
Default

force

Boolean

Force regeneration of the asset

false

Response (200 OK): Binary asset file

POST /:id/renderings

Requests rendering processing for the specified item.

Accepts: multipart/form-data Generates: application/json

Form Parameters:

  • settings: Rendering settings as JSON

Response (201 CREATED): Asset processing object see Asset Processing JSON object

POST /:id/3d-exports

Requests 3D export processing for the specified item.

Accepts: multipart/form-data Generates: application/json

Form Parameters:

  • settings: Export settings as JSON

Response (201 CREATED): Asset processing object see Asset Processing JSON object

POST /:id/conversions

Converts an asset from one type to another (e.g., static-to-configurable).

Accepts: multipart/form-data Generates: application/json

Form Parameters:

  • sourceId: Source item combined ID

  • type: Conversion type (e.g., "static-to-configurable")

  • settings: Conversion settings as JSON

Response (201 CREATED): Asset processing object see Asset Processing JSON object

POST /:id/topImage

Deprecated since 2.41.3 - March 2025 - Use PUT /:id (multipart) with type="topImage" instead.

POST /:id/perspectiveImage

Deprecated since 2.41.3 - March 2025 - Use PUT /:id (multipart) with type "perspectiveImage" instead.

POST /:id/perspectiveImageHD

Deprecated since 2.41.3 - March 2025 - Use PUT /:id (multipart) with type "perspectiveImageHD" instead.

POST /:id/threeDimensionalAssets

Deprecated since 2.41.3 - March 2025 - Use PUT /:id (multipart) with type="source" instead.

POST /:id/assets

Deprecated since 2.41.3 - March 2025 - Use POST / - see CatalogController batch item import instead.

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.

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

POST /:id/threeDimensionalAssets

Deprecated since 2.41.3 - May 2024 - Use PUT /:id (multipart) instead

Requesting 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.

PreviousElementAssetsNextMaterialController

Last updated