First steps with Product API

Business Case:

KPI to be measured

Bookmark this resource Follow

Ask a question

Was this article helpful? 0 out of 0 found this helpful

 

In this article we present a list of use cases about the usage of THRON Product API. If you are a developer as well as an external integrator working for a company that has chosen THRON, here you find a series of best practices and tools to help you being autonomous in your day-by-day activities with product information and content, from product information assets to applications development. 

 

Index of the article

1. Basic glossary

2. What you can do with Product API

    • Product API 
    • Link API

3. Which kind of content you can associate to products

    • Representative content
    • Informative content

4. Standard flow when working with Product API

5. Use case – Product API

6. Use case – Link API

 

1.BASIC GLOSSARY

Here you find a brief list of terms useful to understand and contextualize the content of this article. For a more complete list of terms, you can refer to THRON Glossary. 

 

PRODUCT
The word Product refers to the product code (SKU) that a company associates to a specific item. Products can be enriched with a series of characteristics and attributes and with a set of representative and/or informative contents: all these elements together build the product sheet. When the product-content association takes place, the representative content associated to an SKU inherit product characteristics in the form of tags. 

 

PRODUCT ID

The product ID is an alphanumerical code that represents the THRON internal reference for a specific product. It is created in THRON and it is used for Product API calls.

 

ALIAS
The Alias is an external product identifier, assigned by the company to each item. It is typically used to represent a product code, such as an SKU or an EAN.

An Alias can be

    • Unique: it can be assigned to only one product (one product id), for this reason it identifies one product univocally; it is useful in case it corresponds to the SKU or EAN code of the product
    • Non-unique: the same alias can be assigned to more than one product; usually, the non-unique Alias corresponds to the Alias of the Product Model that has been inherited by Product Variants.

 

LINK

The Links represent the connections between Products and Contents in THRON when we perform a Content-Product association. This link can be representative or informative, depending on the kind of content we are associating to products. When contents are linked to one or more products through a representative link, they inherit product characteristics in the form of tags: in this way, they can be filtered or searched in THRON using product features; moreover, any visit on the content will be also applied to product features for intelligence purposes.

 

2.WHAT YOU CAN DO WITH PRODUCT API

Basically, product API work on product information while content API work on content information.


Product API are divided in two main categories: Product API and Link API. In both cases, when working with API you can act on a single product or work massively on more than one product at a time.

    • Product API are those needed to manage products and can be used to perform actions such as product management, change or removal.
    • Link API are those needed to manage operations regarding content-product association. For example, you can use Link API to associate content to products or to retrieve content that have been associated to a specific product. 

 

3.WHICH KIND OF CONTENT YOU CAN ASSOCIATE TO PRODUCTS

As we briefly anticipated in the description of the term “Link”, in THRON you can associate one or more content to one or more products. This link can be of two kinds, depending on the content type: representative or informative.

 

    • Representative content. The aim of representative content is that of representing, also visually, a certain product (SKU). Usually, representative content are images (also 360° one), video (including panorama video) and playlist, but also technical sheets. You can associate a maximum of 500 representative content to each SKU.
    • Informative content. Informative contents are in support of a product and they have the objective of giving additional information about it. There is no limit to the number of informative contents that can be associated to each SKU.

 

As representative contents inherit product information, they are the ones that can be found and ordered in THRON DAM PLATFORM through the product id.

 

To modify the purpose of a content from representative to informative or vice-versa, you can use the following service: https://hub-product.thron.com/api/v1/docs/#/update-product-content-link-header

 

4.STANDARD FLOW WHEN WORKING WITH PRODUCT API

Here below you find a standard flow of work that should be followed every time you work with Product API.

Now, you have a new content in THRON, complete with

  • the link to product information
  • the new tag, inherited by the linked product.

 

 

5.USE CASES: PRODUCT API

[dropdown:How to find a product or a list of products: LIST PRODUCTS]

The LIST PRODUCTS service can be used both to retrieve a list of products (without filters) or a specific product (by product id or alias).


In case of multiple products queries, you can also filter them by id or alias. By default, the list is ordered by creation date (from the least recent one), but a custom sorting is possible too. 


This service is paginated; use the cursor and limit parameters to retrieve a specific page of products.

 

Examples

  • List product by Product ID
    GET - https://[clientId]-product.thron.com/api/v1/products/[clientId]?ids=612e3b36f6e6367fb03e
  • List products by Product ID, ordered by last update, with 25 results per page
    GET - https://[clientId]-product.thron.com/api/v1/products/[clientId]?ids=[Product ID]&sort=lastModified_A&limit=25
  • List product by Alias list:
    GET - https://[clientId]-product.thron.com/api/v1/products/[clientId]?aliases=[your alias]

[/dropdown]

[dropdown:How to find products: SEARCH PRODUCTS]

The SEARCH PRODUCTS service can be used to find products by characteristics and metadata.


Note: fulltext search is allowed on product metadata

 

POST - Request URL: https://[clientId]-product.thron.com/api/v1/search/products/[clientId]

 

Examples

  • Text search example:

BODY:

{

"text": {

"value": "<Your search text string>"

},

"limit": 25,

"sort": [{

"rank": {

"order": "desc"

}

}],

"clientId": "<clientId>"

}

 

  • SEARCH PRODUCTS by Alias:

BODY

{

"aliases": {

"op": "prefix",

"values": ["<Your Alias>"]

},

"limit": 25,

"sort": [{

"lastModified": {

"order": "desc"

}

}],

"clientId": "<clientId>"

}

 

  • SEARCH PRODUCTS by characteristics (tag):

BODY

{

"tags": {

"op": "and",

"values": [{

"op": "and",

"values": [{

"classificationId": "<classificationId>",

"id": "<TagId>"

}]

}]

},

"limit": 25,

"sort": [{

"lastModified": {

"order": "desc"

}

}],

"clientId": "<clientId>"

}

 

By default, the results of the search are ordered by creation date, from the least recent one. It is also possible to specify a custom sorting.

 

With text search, the list will be ordered by ranking by default. This service is paginated; use the cursor and limit parameters to retrieve a specific page of products.

[/dropdown]

[dropdown:How to create one or more products: CREATE PRODUCTS]

The CREATE PRODUCTS service can be used to create one or more products with a set of specified parameters.

You need to indicate at least one alias (product code), while all the other parameters are optional.

 

Examples

  • How to create a product with product attributes as tags (for example product category, season, etc.) 

POST - https://[clientId]-product.thron.com/api/v1/products/[clientId]

BODY

{

"name": [{

"lang": "EN",

"value": "<Product Name>"

}],

"description": [],

"aliases": [{

"value": "<Product Name>",

"description": "SKU",

"unique": true

}],

"tags": [{

"id": "tagId-1",

"classificationId": "<classificationId>"

}, {

"id": "tagId-2",

"classificationId": "<classificationId>"

}],

"clientId": "<clientId>"

}

[/dropdown]

[dropdown:How to modify or update products: UPDATE PRODUCTS]

The UPDATE PRODUCTS service can be used to update the parameters of a product, using its product id. 

When you use this service, you must specify the product parameters you want to update. Non specified parameters will not be updated: this service works on parameters replace mode. This means that if you want to add, for example, a new tag, you need to specify all the existing tags plus the new one.

 

Examples

  • How to add the tag “tagId-3” to a product

PUT - https://[clientId]-product.thron.com/api/v1/products/[clientId]/[ProductId]

BODY

{

"tags": [{

"id": " tagId-1",

"classificationId": "<classificationId>"

}, {

"id": " tagId-2",

"classificationId": " <classificationId>"

 

}, {

"id": " tagId-3",

"classificationId": " [classificationId]"

}],

"aliases": [{

"value": "<Your SKU>",

"description": "SKU",

"unique": true

}],

"name": [{

"lang": "EN",

"value": "<Your SKU>"

}],

"clientId": "<clientId>"

}

[/dropdown]

[dropdown:How to remove a product: DELETE PRODUCTS]

The DELETE PRODUCTS service can be used to remove a product, using its product id. Once removed, a product will no longer be accessible and will be unlinked from all contents.

 

DELETE PRODUCTS service - https://[clientId]-product.thron.com/api/v1/products/[clientId]/[Product_ID]

[/dropdown]

[dropdown:How to retrieve a list of product update jobs: LIST PRODUCT UPDATE JOBS]

This service can be used to retrieve a list of jobs launched to update products. It is useful to collect information on the status of a specific asynchronous job to update products.

 

This service is paginated; use the cursor and limit parameters to retrieve a specific page of jobs.

 

GET - https://[clientId] -product.thron.com/api/v1/productupdatejobs/[clientId]

[/dropdown]

[dropdown:How to create a product update job: CREATE PRODUCT UPDATE JOBS]

This service can be used to create a job to update products. It enqueues a new asynchronous job to update products. Use this service to update multiple products identified by search parameters.

 

The action parameter defines the type of operation; it can be either “upsert” (to add or update values) or “remove” (to remove values).

 

If the operation is an “upsert”, the update will insert a new object or replace an existing one based on the following conditions:

  • tag: replace if a tag with the same classificationId and tagId exists
  • metadata: replace if a metadata with the same classificationId and key exists
  • name: replace if a value with the same lang exists
  • description: replace if a value with the same lang exists
  • alias: replace (description) if an alias with the same value is found.

 

If the operation is a “remove”, the update will remove properties based on:

  • tag: classificationId and tagId
  • metadata: classificationId, key and lang for string metadata; classificationId and key for the other types
  • name, description: lang
  • alias: value (the update will fail if it tries to remove the only alias in a product).

POST - https://[clientId]-product.thron.com/api/v1/productupdatejobs/[clientId]

 

Examples

  • Objective: search for products that have an alias with value “alias1” and adds to every product an alias with value “alias2”

BODY:

{ 

   "query":{ 

      "aliases":{ 

         "op":"equal", 

         "values":[ 

            "alias1" 

         ] 

      } 

   }, 

   "action":"upsert", 

   "values":{            

      "aliases":[ 

         { 

            "value":"alias2", 

            "description":"description",            

         } 

      ] 

 

   } 

 

}

 

  • Objective: search for products that have an alias with value “alias1” and remove form every product the alias with value “alias2”

BODY:

{ 

   "query":{ 

      "aliases":{ 

         "op":"equal", 

         "values":[ 

            "alias1" 

         ] 

      } 

   }, 

   "action":"remove", 

   "values":{            

      "aliases":[ 

         { 

            "value":"alias2", 

            "description":"description"          

         } 

      ] 

 

   } 

}

[/dropdown]

[dropdown:How to retrieve a list of product delete jobs: LIST PRODUCT DELETE JOBS]

This service can be used to retrieve a list of jobs launched to delete products. It is useful to collect information on the status of a specific asynchronous job to delete products.

 

This service is paginated; use the cursor and limit parameters to retrieve a specific page of jobs.

 

GET - https://[clientId]-product.thron.com/api/v1/productdeletejobs/ [clientId]

[/dropdown]

[dropdown:How to create a product delete job: CREATE PRODUCT DELETE JOBS]

This service can be used to create a job to delete products. It enqueues a new asynchronous job to remove products.

 

Use this service to remove multiple products identified by search parameters.

POST - https://[clientId]-product.thron.com/api/v1/productdeletejobs/[clientId]

 

Examples

  • Objective: deleting all the products that have an alias with value “alias1”

Body

{

  "query": {

    

    "aliases": {

      "op": "equal",

      "values": [

        "alias1"

      ]

    }

 

  }

}

 

  • Objective: delete all the products that have the tags ID_TAG1  e ID_TAG 2

Body

{

"query": {

 

"tags": {

"op": "and",

"values": [{

"op": "and",

"values": [{

"id": "ID_TAG1",

"classificationId": "ID_CASS"

},

                {

"id": "ID_TAG2",

"classificationId": "ID_CASS"

}]

}]

}

}

}

[/dropdown]

[dropdown:How to upload a file for products import: UPLOAD AN IMPORT CSV FILE]

The UPLOAD AN IMPORT CSV FILE service can be used to upload the CSV file for products import. It returns all the information required to upload a new temporary file into S3.

 

Supports a UTF-8 encoded csv file with doublequote as quote character (to be used in case of values with reserved characters). 

 

Here below you find the process:

[/dropdown]

[dropdown:How to retrieve a list of product import jobs: LIST PRODUCT IMPORT JOBS]

This service can be used to retrieve a list of jobs launched to import products. It is useful to collect information on the status of a specific asynchronous job to import products.

 

This service is paginated; use the cursor and limit parameters to retrieve a specific page of jobs.

GET - https://[clientId]-product.thron.com/api/v1/productimports/[clientId]

[/dropdown]

[dropdown:How to create a creation import job: CREATE IMPORT JOBS]

This service can be used to create a job to import products. It enqueues a new asynchronous job to import products.

 

The instructions for the import are supplied in a CSV file loaded on S3 through the use of the “internalS3files” endpoint.

 

The CSV file must be composed of a first row of user-defined column names (the header) and a series of rows (the operations), one for each product that should be added or updated.

 

Note that the rows are not processed in order, therefore if more than one row points to the same product, some of the operations may be overwritten.

 

The meaning of each column in the CSV is defined by the schema parameter.

 

POST- https://[clientId]-product.thron.com/api/v1/productimports/[clientId]

 

Examples

 

  • Import a test file

{

   "schema":{

      "uniqueAlias":{

         "column":"codice_prodotto",

         "description":{

            "defaultValue":"ean"

         },

         "policy":"addwhenmissing"

      },

      "additionalOperations":[

         {

            "name":{

               "column":"nome_prodotto",

               "language":{

                  "defaultValue":"EN"

               },

               "policy":"upsert"

            }

         },

         {

            "name":{

               "column":"nome_prodotto",

               "language":{

                  "defaultValue":"IT"

               },

               "policy":"upsert"

            }

         },

         {

            "description":{

               "column":"desc_prodotto",

               "language":{

                  "defaultValue":"IT"

               },

               "policy":"upsert"

            }

         },

         {

            "description":{

               "column":"desc_prodotto",

               "language":{

                  "defaultValue":"EN"

               },

               "policy":"upsert"

            }

         },

         {

            "tag":{

               "column":"brand",

               "classificationId":"q1j33l",

               "tagConflict":{

                  "policy":"replaceWithNew",

                  "subset":"parent",

                  "tagId":"ccd8b962fbbe43e8bbe7a5b55962d177"

               }

            }

         },

         {

            "stringMetadata":{

               "column":"colore_prodotto",

               "classificationId":"q1j33l",

               "key":"colore",

               "policy":"upsert"

            }

         }

      ]

   },

   "source":{

      "internalS3File":{

         "id":"<ID FILE UPLOAD>"

      }

   },

   "name":"Test_product-import"

}

[/dropdown]

[dropdown:How to retrieve a list of failed import rows: LIST FAILED IMPORT ROWS]

This service can be used to retrieve a list rows that failed during an import job.

 

GET - https:// [clientId]-product.thron.com/api/v1/productimports/ [clientId]/[importId]/failedrows

 

You need to specify the jobid that need to be verified (parameter importId).

[/dropdown]

 

6.USE CASES: LINK API

[dropdown:How to retrieve product-associated contents: LIST PRODUCT LINKS]

This service can be used to retrieve all the contents that have been associated to a product and vice-versa, optionally filtered by product or content id.

This service does not support external or pretty ids to identify contents. If you need to retrieve all content linked to a product given a unique identifier (like id or unique alias) you can fill the parameter productSelector.

 

This service is paginated; use the cursor and limit parameters to retrieve a specific page of links.

 

Examples

 

  • Example of a call to get all the content linked to a product, ordered by creation date.
    GET - https://[clientId]-product.thron.com/api/v1/productcontentlinks/[clientId]?productId=[Product_ID]&sort=created_A

 

  • Example of a call to get all the content linked to a product, ordered by creation date.
    GET - https://[clientId]-product.thron.com/api/v1/productcontentlinks/[clientId]?productId=[Product_ID]&purpose=nopurpose&sort=created_A

[/dropdown]

[dropdown:How to create a link between a product and a content: CREATE PRODUCT LINKS]

This service can be used to create a link between a product and a content with some specified parameters. Use this service to add a single content to a product.

Use the purposes attribute to specify the relation type. Note that the same purpose cannot be added more than once; any redundant purpose will be ignored.

 

A product can be linked to at most 500 assets with 'representation' purpose. An asset can be linked to at most 500 products with 'representation' purpose. 

 

Generic properties for the link can be applied with the attribute’s parameter.

This service supports external or pretty ids to identify contents.

 

  • Example of link between a product and a representative content

POST - https://[clientId]-product.thron.com/api/v1/productcontentlinks/[clientId]

 

BODY

{

  "contentId": "<xcontentId>",

  "productId": "<Product_ID>",

  "purposes": [

    "representation"

  ]

}

[/dropdown]

[dropdown:How to remove a link between a product and a content: DELETE PRODUCT LINKS]

This service can be used to remove a link between a product and a content identified by the specified parameters. Use this service to remove a single content from a product. This service does not support external or pretty ids to identify contents.

 

  • Example of unlink between a content and a product

DELETE - https://[clientId]-product.thron.com/api/v1/productcontentlinks/[clientId]

 

BODY

{

  "contentId": "<xcontentId>",

  "productId": "<Product_ID>"

}

[/dropdown]

[dropdown:How to update a link between a product and a content: UPDATE PRODUCT LINKS]

This service can be used to update a link between a product and a content with the specified parameters.

Use the purposes attribute to specify the relation type. Note that the same purpose cannot be added more than once; any redundant purpose will be ignored.

 

A product can be linked to at most 500 assets with 'representation' purpose. An asset can be linked to at most 500 products with 'representation' purpose. 

 

Generic properties for the link can be applied with the attribute’s parameter.

This service supports external or pretty ids to identify contents.

 

  • Example of how to make a content representative and modify its position.

PUT - https://[clientId]-product.thron.com/api/v1/productcontentlinks/[clientId]/[ProductContentLink_ID]

 

BODY

{

"purposes": ["representation"],

"position": 2

}

[/dropdown]

[dropdown:How to retrieve a list of product link jobs: LIST PRODUCT LINK JOBS]

This service can be used to retrieve a list of jobs launched to link products to contents. It is useful to collect information on the status of a specific asynchronous job to link content to products.

 

This service is paginated; use the cursor and limit parameters to retrieve a specific page of jobs.

 

GET - https://[clientId]-product.thron.com/api/v1/linkjobs/[clientId]?ids=[Product_ID]&limit=1

[/dropdown]

[dropdown:How to create a product link job: CREATE PRODUCT LINK JOBS]

This service can be used to create a job to link products to contents. It enqueues a new asynchronous job to link content to a product. Use this service to link (or unlink) multiple contents to a product identified by id or alias.

If the specified alias identifies multiple products, the contents will be added to all identified products. This service supports external or pretty ids to identify contents.

 

It is not possible to add the same content to a product more than once; adding some content to a product that is already linked to it will update the purpose (if specified). The service returns an id, needed to query the job for its status.

 

  • Example of link to representative content

 

POST - https://[clientId]-product.thron.com/api/v1/linkjobs/[clientId]

 

BODY

{

"action": "link",

"content": {

"ids": ["<xcontentId1, xcontentId2>"]

},

"product": {

"ids": ["<Product_ID1, Product_ID2>"]

},

"purposes": ["representation"],

"clientId": "<clientId>"

}

 

  • Example of link to an informative content

 

POST - https://[clientId]-product.thron.com/api/v1/linkjobs/[clientId]

 

BODY

 

{

"action": "link",

"content": {

"ids": ["<xcontentId>"]

},

"product": {

"ids": ["<Product_ID>"]

},

"clientId": "<clientId>"

}

[/dropdown]

Was this article helpful?
0 out of 0 found this helpful

Have any question?

Open a ticket
Comments