TagController

Overview

• Description

  • Tag object

  • JSON Fields

  • CSV fields

• API Reference

  • GET /

  • POST /

  • GET /:id

  • PUT /:id (json)

  • PUT /:id (multipart)

  • DELETE /:id

  • DELETE /:id/:assetType

  • GET /:id/items

  • GET /:id/materials

  • GET /:id/components

  • GET /:id/parentTags

Description

Path /v2/tags

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

Tag Object

An example for a tag JSON object.

{
    "id": "products",
    "global": true,
    "created": "2016-08-01T14:35:53.000Z",
    "updated": "2016-11-28T16:48:34.000Z",
    "links": {
        "items": "/tags/products/items",
        "materials": "/tags/products/materials",
        "parentTags": "/tags/products/parentTags"
    },
    "catalog": "roomle_white_furniture",
    "label": "Products",
    "language": "en",
    "items": ["roomle_white_furniture:door"],
    "tags": [
        "product_beds",
        "product_lighting",
        "product_miscellaneous",
        "product_mockup",
        "product_seating",
        "product_storage",
        "product_tables"
    ],
    "parents": [
        "roomle_white_furniture_root"
    ],
    "hidden": false,
    "visibilityStatus": 0
}

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

{
    "tag": 
        {tagObject},
    "tags": [
        {tagObject1},
        {tagObject2},
        ...
    ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": 2,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}

JSON Fields

• id

• global

• created

• updated

• links - list of links to related resources

  • items

  • materials

  • components

  • parentTags

• catalog - tha catalog this tag belongs to

• label

• language

• items - list of item ids connected to this tag

• tags - child tags

• parents - parent tags

• 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)

CSV fields

• id: identifier of a tag (deprecated)

• tag_id : identifier of the tag

• 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 TagTranslation.

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

• png_icon: current png icon for this tag

• svg_icon: current svg icon for this tag

• inspiration_image: current inspiration image for this tag

• global: is the tag global visible?

• hidden: deprecated by visibilityStatus

• visibilityStatus : possible values

  • 0 : SHOWN (visible everywhere)

  • 1 : SHOWN_IN_CMS (visible only in cms context)

  • 2 : ARCHIVED (hidden everywhere)

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

• material_ids: all connected material combined ids separated by ' ' (whitespace)

• item_ids: all connected item combined ids separated by ' ' (whitespace)

• component_ids: all connected component combined ids separated by ' ' (whitespace)

• parent_tag_ids: ids of parent tags separated by ' ' (whitespace)

API Reference

GET /

List of all tags matching the filter and visible to the Client

Generates: application/json

Response (200 OK): Returns a list of Tag JSON object.

Query Parameters

Name	Type	Comment
ids[]	List of strings	filters the result to the given tag ids
catalogs[]	List of strings	filters the result to the given catalog ids
global	Boolean	If true returns only global tags, default is false

POST /

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

Accepts: application/json Generates: application/json

Body: Tag JSON object

Response (201 CREATED): Tag JSON object

GET /:id

Returns a specific tag.

Generates: application/json

Response (200 OK): Tag JSON object

PUT /:id (json)

Updates a specific tag. Assets needs to be uploaded explicitly (using PUT /:id (multipart)).

Accepts: application/json Generates: application/json

Body: Tag JSON object

Response (200 OK): updated Tag JSON object

PUT /:id (multipart)

updates assets on an tag

Accepts: multipart-formdata Generates: application/json

parameters:

• the data, either as file or as URL. if both are provided, the URL is used

  • file : datafile to be uploaded

  • fileUrl: the publicly available url to the datafile

• type: type of the asset

possible types are

• "svgIcon"

• "pngIcon"

• "inspirationImage"

Response (200 OK): updated Tag JSON object with updated asset

For more information on the assets, please check ElementAssets

DELETE /:id

Deletes a specific tag.

Response (204 NO CONTENT): deleted

DELETE /:id/:assetType

deletes an asset on a specific tag

possible types are

• "svgIcon"

• "pngIcon"

• "inspirationImage"

Response (204 NO CONTENT): deleted

For more information on the assets, please check ElementAssets

GET /:id/items

Generates: application/json

Returns all items which are assigned to this tag.

Response (200 OK): List of Item JSON object

GET /:id/materials

Generates: application/json

Returns all materials which are assigned to this tag.

Response (200 OK): List of Material JSON object

GET /:id/components

Generates: application/json

Returns all components which are assigned to this tag.

Response (200 OK): List of Component JSON object

GET /:id/parentTags

Generates: application/json

Returns all parent tags of this tag.

Response (200 OK): List of Tag JSON object