MaterialController

Overview

• Description

  • Material object

  • Json Fields

  • CSV fields

• API Reference

  • GET /

  • POST /

  • GET /:id

  • PUT /:id (json)

  • PUT /:id (multipart)

  • GET /id/thumbnail

  • DELETE /:id/:assetType

  • GET /:id/textures

Description

Path /v2/materials

Handles all request regarding materials: creating, updating, deleting.

Material object

An example for a material json object.

{
  "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.

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

Response (201 CREATED): Material JSON object

GET /:id

Returns a specific material.

Generates: application/json

Response (200 OK): 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)).

Accepts: application/json Generates: application/json

Body: Material JSON object

Response (200 OK): updated 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 with updated asset

For more information on the assets, please check ElementAssets

POST /:id/thumbnail - DEPRECATED

since 2.43.0 - March 2024

use 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

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.