# MaterialController ## Overview * [Description](#description) * [Material object](#material-object) * [Json Fields](#json-fields) * [CSV fields](#csv-fields) * [API Reference](#api-reference) * [GET /](#get-) * [POST /](#post-) * [GET /:id](#get-id) * [PUT /:id (json)](#put-id-json) * [PUT /:id (multipart)](#put-id-multipart) * [GET /id/thumbnail](#get-idthumbnail) * [DELETE /:id/:assetType](#delete-idassettype) * [GET /:id/textures](#get-idtextures) ## Description Path /v2/materials Handles all request regarding materials: creating, updating, deleting. ### Material object An example for a material json object. ```json { "externalIdentifier": "materialExtId1", "version": 0, "id": "catalog1:materialExtId1", "color": "128,128,128", "shading": { "basecolor": { "r": 0.9019607843137255, "g": 0.5823529411764706, "b": 0.6470588235294118 }, "specularity": 0.9999999999999999, "metallic": 0, "roughness": 0.6, "alpha": 1.0 }, "properties": { "property1": "value1", "property2": "value2", "property3": "value3", "property4": "value4" }, "thumbnail": "thumb", "asset": "asset/web/3/assetfile", "textures": [ 1 ], "tags": [ "tag1", "tag2" ], "label": "mat1En", "language": "en", "catalog": "catalog1", "group": "catalog1:group1", "links": { "textures": "/materials/catalog1:materialExtId1/textures" }, "hidden": false, "active": true, "activeFrom": "2020-01-01T00:00:00.000Z", "activeTill": "2022-10-01T00:00:00.000Z", "sort": 13, "updated": "1970-01-01T00:00:00.000Z", "created": "1970-01-01T00:00:00.000Z", "visibilityStatus": 0 } ``` Responses are usually wrapped in a meta object, which contains additional information about the response and may contain a single material or a list of materials. ``` { "material": {materialObject}, "materials": [ {materialObject1}, {materialObject2}, ... ], "meta": { "lastUpdated": "2018-01-23T09:15:39.000Z", "cached": false, "total": 2, "serverTime": "2019-03-14T12:29:08.549Z" } } ``` ### Json Fields * externalIdentfier * version * id * color * shading * properties * thumbnail * asset * textures * tags * label * language * catalog * group * links * hidden - deprecated, superseded by visibilityStatus * active - deprecated, superseded by visibilityStatus * activeFrom * activeTill * updated * created * visibilityStatus : note that this value is computed from activeFrom and activeTill if those are set * 0 : SHOWN (visible everywhere) * 1 : SHOWN\_IN\_CMS (visible only in cms context) * 2 : ARCHIVED (hidden everywhere) ### CSV fields * material\_id * Translations - 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 MaterialTranslation. * description\_{languageCode}: languageCode in ISO standard can be "en" or "de" for example and will be the current value of this language in the MaterialTranslation. * shading - contains the serialized shading object, if present in the database * tag\_ids - contains a list of tag ids connected with this material * active - boolean value if the material is active. If activeFrom and/or activeTill are set, it is overridden by the timespan. If set while no activeFrom or activeTill columns are present, setting active will remove previously set time spans * activeFrom - unix timestamp, is null if no value, sets a starting point in time for the material to be active * activeTill - unix timestamp, is null if no value, sets an ending point in time for the material to be active * sort: can be an integer or null, if there is no value for this field * Embeded textures - can be multiple, repeating with different prefix - tex0\_ , tex1\_, .... We always have a set of the following columns: * tex0\_mapping * tex0\_height * tex0\_width * tex0\_mmHeight * tex0\_mmWidth * tex0\_tileable * visibilityStatus : * 0 : SHOWN (visible everywhere) * 1 : SHOWN\_IN\_CMS (visible only in cms context) * 2 : ARCHIVED (hidden everywhere) ## API Reference ### GET / List of all materials matching the filter and visible to the Client Generates: application/json Query Parameters | Name | Type | Comment | | ------------- | ------- | ---------------------------------------------------------------------------- | | embedTextures | Boolean | If true the textures are included as embedded json objects, default is false | Response (200 OK): Returns a list of [Material json objects](#material-json-object). Query Parameters | Name | Type | Comment | | ------------- | --------------- | ------------------------------------------------------------------------------------- | | ids\[] | List of strings | filters the result to the given material ids | | tags\[] | List of strings | filters the result to the given tag ids | | groups\[] | List of strings | filters the result to the given group ids | | catalog | String | filters the result to the given catalog id | | catalogs\[] | List of strings | filters the result to the given catalog ids | | embedTextures | Boolean | If true the textures are included as embedded json objects, default is false | | locale | String | The locale to use for the labels, default is english | | includeAll | Boolean | If true all materials are returned, otherwise only the visible ones, default is false | ### POST / Creates a new material in the catalog provided in the body. Accepts: application/json Generates: application/json Body: [Material JSON object](#material-json-object) Response (201 CREATED): [Material JSON object](#material-json-object) ### GET /:id Returns a specific material. Generates: application/json Response (200 OK): [Material JSON object](#material-json-object) Query Parameters | Name | Type | Comment | | ------------- | ------- | ---------------------------------------------------------------------------- | | embedTextures | Boolean | If true the textures are included as embedded json objects, default is false | | locale | String | The locale to use for the labels, default is english | ### PUT /:id (json) Updates the metainformation of a material. Thumbnail needs to be uploaded explicitly (using [PUT /:id (multipart)](#put-id-multipart)). Accepts: application/json Generates: application/json Body: [Material JSON object](#material-json-object) Response (200 OK): updated [Material JSON object](#material-json-object) ### PUT /:id (multipart) updates assets on an material Accepts: multipart-formdata Generates: application/json parameters: * file : datafile to be uploaded * type: type of the asset possible types are: * "thumbnail" Response (200 OK): updated [Material JSON object](#material-json-object) with updated asset For more information on the assets, please check [ElementAssets](https://docs.roomle.com/rubens/rest-api/rest-api-reference/elementassets#uploadable-types) ### POST /:id/thumbnail - DEPRECATED since 2.43.0 - March 2024 **use** [**PUT /id (multipart)**](#put-id-multipart) **instead** ### GET /:id/thumbnail Response (307 TEMPORARY REDIRECT): the URL of the thumbnail for this material. If the response status is 403, you are not allowed to see the material. If the response status is 404, the material has no thumbnail. ### DELETE /:id/:assetType deletes an asset on a material possible types are images: * "thumbnail" Response (204 NO CONTENT): deleted For more information on the assets, please check [ElementAssets](https://docs.roomle.com/rubens/rest-api/rest-api-reference/elementassets#uploadable-types) ### GET /:id/textures Returns a list of textures that are associated with this material. Generates: application/json Response (200 OK): Returns a list of [Texture json objects](https://docs.roomle.com/rubens/rest-api/rest-api-reference/texture#texture-json-object).