General description

Products API v2 aims at a much simpler and straight-forward use of the endpoints where nomenclature values are needed. The changes are therefore in the complete removal of enumerated values, which are now replaced with their string counterparts. Below you can find an overview of the changes, concerning each value that was previously enumerated. If you are more interested in the changes for a particular endpoint, please refer the menu on the left.

Data types

The most prominent changes concern the value data types. Products API v2 no longer requires adding the value data type when a request for creating or editing a property is sent.

Important to note: The value should still comply with the data type of the property and a validation error will be returned if this is not the case. It is however no longer needed to declare the value data type in the request body itself.

v1:

"values": [
  {
    "value": "My test string value",
    "ValueDataTypeId": "5",
    ...
  }

v2:

"values": [
  {
    "value": "My test string value",
    ...
  }

When it comes to the endpoints where properties are returned, the property's data type will be returned with a string value.

"values": [
  {
    "value": "string",
    "valueGuid": "string",
    "operator": "string",
    "dataType": "string"
  }
]

Specific product types

Specific product types are no longer enumerated and should be entered as a string in the requests. They will also be returned as a string value in the responses.

v1:

"constructionObjectGuid": "examplestring",
"specificType": 1,
"identifiers": [

v2:

"constructionObjectGuid": "examplestring",
"specificType": "Regular",
"identifiers": [

Country-specific identifiers

Not all countries of distribution have their own specific identifiers in addition to the main ones (GTIN and SPN), but for those which do, we can add a value for those additional identifiers. Previously they were enumerated, but now we use strings in both the request and response bodies.

v1:

"identifiers": [
  {
    "id": 1,
    "value": "123456789"
  }

v2:

"identifiers": [
  {
    "name": "nobbr",
    "value": "123456789"
  }

Operators

Whenever properties with data type integer and float number are created, it should be additionally specified if it is an exact value or a range. In order to do that, one needs to add an operator. In Products API v2 we use strings, instead of numbers:

v1:

"values": [
  {
    "value": "My test string value",
    "operatorId": 1,
  }

v2:

"values": [
  {
    "value": "My test string value",
    "operator": "eq",
  }

Countries

There are a number of countries of distribution for the product that are available in the Products API. In v1 we had a separate endpoint which could return those countries and their enumeration code. In v2 we replace the use of an enumeration code with the use of the two-character ISO 3166 Alpha2 code for both requests and responses.

v1:

{
  "countryId": 1,
  "name": "My test product",

v2:

{
  "country": "NO",
  "name": "My test product",

Cultures and languages

In order to get content in a particular language, that language or culture needs to be specified in the request URL. In v1 we had a separate endpoint which could return those cultures and their enumeration code. In v2 we replace the use of an enumeration code with the use of a string culture code for both requests and responses. The URL parameter is renamed from LanguageCode to culture.

v1:

GET:https://api.cobuilder.com/products-management
/api/v1/products/{id}/properties/values?LanguageCode=nb-NO

v2:

GET:https://api.cobuilder.com/products-management
/api/v2/products/{id}/properties/values?culture=nb-NO

Here's the full list of affected endpoints:

Get property values
Get product standards
Get classifications
Get construction object
Get photos
Get documents
Get components

Other changes

The enumerators are also removed from the error responses. Previously, if a request didn't go through, an error with an error code and an error explanation in a string form was returned. In v2 only the string explanation of the error is returned.

Example for error 400 Bad request:

v1:

{
  "propertyGuid": "examplestring",
  "errorCode": 1,
  "errorCodeName": "NoDataOrInvalidFormat"
}

v2:

{
    "type":"https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title":"One or more validation errors occurred.",
    "status": 400,
    "traceId":"samplestring"
    "errors": {
        "[1]": [
            "Property with guid x has an invalid operator"
         ]
        "[2]": [
            "Property with guid x has an invalid data type"
         ]
    }
}

Create endpoints

Create Product

This is one of the most affected endpoints, as most of the data we require for creating a product was previously enumerated. We have also done a small revision on the response body and renamed the ManufacturedProductID parameter to simply ID. The following parameters now require string values provided: countryID, specificType, identifiers ("name").

Endpoint:

v1:

POST:

https://api.cobuilder.no/products-management/api/v1/products

v2:

POST:

https://api.cobuilder.no/products-management/api/v2/products

Request body changes:

v1:

{
  "countryId": "1",
  "name": "My test product",
  "gtin": "123456",
  "spn": "654321",
  "constructionObjectGuid": "string",
  "specificType": 1,
  "identifiers": [
    {
      "id": 1,
      "value": "123456789"
    }
  ]
}

v2:

{
  "country": "NO",
  "name": "My test product",
  "gtin": "123456",
  "spn": "654321",
  "constructionObjectGuid": "string",
  "specificType": "Regular",
  "identifiers": [
    {
      "name": "nobbnr",
      "value": "123456789"
    }
  ]
}

Respone in v2:

{
  "id": 1000000,
  "name": "My test product",
  "description": "Description preview",
  "manufacturerName": "Cobuilder",
  "countryId": NO,
  "spn": "654321",
  "gtin": "123456",
  "identifiers": [
    {
      "value": "123456789",
      "name": "nobbnr"
    }
  ],
  "specificType": "Regular",
  "isExpired": false,
  "createdOn": "string",
  "changedOn": "string",
  "accountId": "string",
  "parentId": 0
}

Create property values

There are a number of changes in the Create property values endpoint as well. Most importantly, you no longer need to provide the value data type in the request. The value is still validated, but there is no longer need for the data type parameter. The value operators are now also in the form of a string.

Enpoint:

v1:

POST:

https://api.cobuilder.no/products-management/api/v1/products/{id}/properties/values/create

v2:

POST:

https://api.cobuilder.no/products-management/api/v2/products/{id}/properties/values/create

Request body changes:

Example request for a property with data type string:

v1:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "values": [
      {
        "value": "My test string value",
        "ValueDataTypeId": 5,
      }
    ]
  }
]

v2:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "values": [
      {
        "value": "My test string value",
      }
    ]
  }
]

Example request for a property with data type integer:

v1:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "values": [
      {
        "value": "My test string value",
        "ValueDataTypeId": 2, 
        "operatorId": 1, 
      }
    ]
  }
]

v2:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "values": [
      {
        "value": "100",
        "operator": "eq"
      }
    ]
  }
]

Update endpoints

Update Product

Everything remains the same expect the HTTP verb is changed to PATCH in v2.

Endpoint:

v1:

PUT:
https://api.cobuilder.no/products-management/api/v1/products/{id}

v2:

PATCH:
https://api.cobuilder.no/products-management/api/v2/products/{id}

Update property values

The changes in the Update property values endpoint are the same as in the Create property values endpoint. Most importantly, you no longer need to provide the value data type in the request. The value is still validated, but there is no longer need for the data type parameter. The value operators are now also in the form of a string.

Endpoint:

v1:

POST:

https://api.cobuilder.no/products-management/api/v1/products/{id}/properties/values/update

v2:

POST:

https://api.cobuilder.no/products-management/api/v2/products/{id}/properties/values/update

Request body changes:

Example request for a property with data type string:

v1:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "values": [
      {
        "value": "My test string value",
        "ValueDataTypeId": 5,
      }
    ]
  }
]

v2:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "values": [
      {
        "value": "My test string value",
      }
    ]
  }
]

Example request for a property with data type integer:

v1:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "values": [
      {
        "value": "My test string value",
        "ValueDataTypeId": 2, 
        "operatorId": 1, 
      }
    ]
  }
]

v2:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "values": [
      {
        "value": "100",
        "operator": "eq"
      }
    ]
  }
]

Update property values in bulk by SPN

Besides the changes, which are also relevant for the Create and Update property values endpoints, the endpoint for bulk editing of properties has one more parameter change. It is the countryId parameter, which specifies the products' country of distribution. Instead of accepting the enumerated code for the country, the v2 endpoint accepts the ISO 3166 Alpha 2 country code.

Endpoint:

v1:

POST:

https://api.cobuilder.com/products-management/api/v1/products/properties/values/spn-bulk

v2:

POST:

https://api.cobuilder.com/products-management/api/v2/products/properties/values/spn-bulk

Request body changes:

v1:

{
  "spn": "string",
  "countryIds": [
    1
  ],
  "values": [

v2:

{
  "spn": "string",
  "countries": [
    "NO",
  ],
  "values": [

Update product status

We are introducing a new functionality in the Products API v2 - the status of the product can now be changed through the Edit status endpoint.

Depending on whether the product is actively manufactured and distributed in the market or is no longer a part of the manufacturer's product offering, a product can either be active or expired. Active products are visible on the manufacturer's public product catalogue, whereas expired products are archived and visible only for the manufacturer.

Endpoint:

v2:

PATCH:
https://api.cobuilder.com/products-management/api/v2/products/{id}/status

Request body:

{
  "isExpired": "true",
}

Search endpoints

Product search (prev. GetProductList)

In the Product search endpoint you can additionally filter through the products in the product list, base on different criteria. The changes are in the countryId and specificType parameters, which require a string value now.

Endpoint:

v1:

POST:

https://api.cobuilder.no/products-management/api/v1/products/search

v2:

POST:

https://api.cobuilder.no/products-management/api/v2/products/search

Request body changes:

v1:

{
  "filtration": {
    "spn": "123456",
    "gtin": "1234567891234",
    "countryIds": [
      1
    ],
    "specificTypes": [
      1
    ],
    "includeExpired": true
  },
  "pagination": {
    "skip": 0,
    "take": 50
  }
}

v2:

{
  "filtration": {
    "spn": "123456",
    "gtin": "1234567891234",
    "countries": [
      NO
    ],
    "specificTypes": [
      "Regular"
    ],
    "includeExpired": true,
    "filterTopLevelProductLines": true
  },
  "pagination": {
    "skip": 0,
    "take": 50
  }
}

Get endpoints

Get product details

Analogical to the Create Product endpoint, the response of the Get product details endpoint has also undergone a modest transformation. Instead of providing two Cobuilder-specific IDs of the product, we have now removed the one that is not used elsewhere in the API (productId) and renamed what was previously "manufacturedProductId" to simply "id". The ID is the unique reference number for the product that should be used in all GET endpoints for product data.

Endpoint:

v1:

GET:
https://api.cobuilder.com/products-management/api/v1/products/{id}

v2:

GET:
https://api.cobuilder.com/products-management/api/v2/products/{id}

Response body changes:

v1:

{
  "productId": 0, 
  "manufacturedProductId": 0,
  "name": "string",
  "description": "string",
  "manufacturerName": "string",
  "countryId": 0, 
  "spn": "string",
  "gtin": "string",
  "identifiers": [
    {
      "id": 0, 
      "value": "string",
      "name": "string"
    }
  ],
  "specificType": 1,
  "isExpired": true,
  "createdOn": "string",
  "changedOn": "string",
  "accountId": "string",
}

v2:

{
  "id": 0, 
  "name": "string",
  "description": "string",
  "manufacturerName": "string",
  "country": "string" ,
  "spn": "string",
  "gtin": "string",
  "identifiers": [
    {
      "value": "string",
      "name": "string"
    }
  ],
  "specificType": "string",
  "isExpired": true,
  "createdOn": "string",
  "changedOn": "string",
  "accountId": "string",
  "parentId": 0
}

Get property values

There are only a couple of changes in the Get property values endpoint. One of them is in the URL itself - if you want to get the data in a language of your choosing, you will need to add a parameter with a code, signifying the preferred language. Before this parameter was "LanguageCode", and in the new version of the API, it is renamed to "culture". In the response body itself, we have removed the data type and operator enumeration codes and now only return the string values.

Endpoint URL changes:

v1:

GET:

https://api.cobuilder.com/products-management/api/v1/products/{id}/properties/values? languageCode

v2:

GET:

https://api.cobuilder.com/products-management/api/v2/products/{id}/properties/values? culture

Response body changes:

v1:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "propertyTitle": "string",
    "propertyDefaultTitle": "string",
    "unitTitle": "string",
    "unitDefaultTitle": "string",
    "values": [
      {
        "value": "string",
        "valueGuid": "string",
        "valueDataTypeId": 1,
        "operatorId": 1, 
        "operator": "string",
        "valueDataType": "string"
      }
    ]
  }
]

v2:

[
  {
    "propertyGuid": "string",
    "unitGuid": "string",
    "propertyTitle": "string",
    "propertyDefaultTitle": "string",
    "unitTitle": "string",
    "unitDefaultTitle": "string",
    "values": [
      {
        "value": "string",
        "valueGuid": "string",
        "operator": "string",
        "dataType": "string"
      }
    ]
  }
]

Changes in other GET endpoints

The rest of the GET endpoints are affected only through the renaming of the LanguageCode parameter in the URL. Instead of LanguageCode, the parameter is now named culture, see examples below:

Get classifications

Endpoint URL changes:

v1:

GET:

https://api.cobuilder.com/products-management/api/v1/products/{id}/classifications? languageCode

v2:

GET:

https://api.cobuilder.com/products-management/api/v1/products/{id}/classifications? culture

Get construction object

Endpoint URL changes:

v1:

GET:

https://api.cobuilder.com/products-management/api/v1/products/{id}/construction-object? languageCode

v2:

GET:

https://api.cobuilder.com/products-management/api/v1/products/{id}/construction-object? culture

Get documents

Endpoint URL changes:

v1:

GET:https://api.cobuilder.com/products-management/api/v1/products/{id}/documents?
LanguageCode=&Skip=&Take=

v2:

GET:https://api-cobuilder.com/products-management/api/v2/products/{id}/documents?
culture=&skip=&take=

Get photos

Endpoint URL changes:

v1:

GET:https://api.cobuilder.com/products-management/api/v1/products/{id}/photos?
LanguageCode=&Skip=&Take=

v2:

GET:https://api.cobuilder.com/products-management/api/v1/products/{id}/photos?
languageCode=&skip=&take=

Get BIM objects

Endpoint URL changes:

v1:

GET:

https://api.cobuilder.com/products-management/api/v1/products/{id}/bim-objects? languageCode

v2:

GET:

https://api.cobuilder.com/products-management/api/v1/products/{id}/bim-objects? culture

Get BIM files

Endpoint URL changes:

v1:

GET:https://api.cobuilder.com/products-management/api/v1/products/{id}/bim-files?
LanguageCode=&Skip=&Take

v2:

GET:https://api.cobuilder.com/products-management/api/v1/products/{id}/bim-files?
culture=&skip=&take=

Get components

Endpoint URL changes:

v1:

GET:https://api.cobuilder.com/products-management/api/v1/products/{id}/components?
LanguageCode=&Skip=&Take=

v2:

GET:https://api.cobuilder.com/products-management/api/v1/products/{id}/components?
culture=&skip=&take=

Delete endpoints

There are no changes affecting the Delete endpoints.

Removed endpoints

As we do not use any enumerated data in the new version of the Products API, the nomenclature endpoints from API v.1 were deprecated and were not included in the API v.2. You can find the list of available countries, languages, data types and operators in the new Relevant nomenclatures page.