RESTful API changelog
- Product filtering by LCANew fields have been introduced for filtering products, related to LCA: "database" and "uuid" of the dataset.
- Improved API filtering data error messagesImprovements have been made to product filtering error messages by indicating incorrect values used in filter conditions.
- New request parameters for querying product dataNew parameters have been introduced in requests for getting product data to enable/disable the last product modification date section ("completeness") and the product description completeness section ("dates-by-type") in the product description.
- Link to EPD in LCA dataA link to the EPD document has been added to the LCA data.
- Remastered modify modes in the "Put product data" requestModification modes of product data in "PUT" requests have been remastered. They are now more intuitive, secure and well-documented (detailed explanations are given for individual product information elements).
- Dynamic LCA (via API)The way of searching and accessing Life Cycle Assessment (LCA) data has been changed from static to dynamic (via API). Access to many different LCA databases has been enabled. When referring to LCA data, the version has been omitted (the reference is always to the latest version of the data).
- New attribute type: "date"The new date attribute type makes it possible to work with and manage date-related information.
- Reference flow information in LCA dataLCA data has been completed with "Reference flow" information.
- All LCA indicator valuesThe values of all LCA indicators can now be retrieved via API with a dedicated request.
- LCA (Life Cycle Assessment)Possibility to read (GET) or write (PUT) an assignment to a product of a set of LCA data from the Oekobaudat database.
- Filtering products by an array of valuesAll "text" fields can now also be filtered by an array of values (up to 200). This makes it possible, for example, to search the API for multiple values for the same identifier. The default operator used when filtering with an array of values is logical "OR".
- New product filteringA new way of filtering products has been implemented, and due to this, new filtering keys have been added with corresponding values adapted to the new filtering. Some of the existing filtering keys become deprecated and will be replaced by new ones.
- Permanent activation of wildcardsProduct filtering using wildcards has been permanently activated for all users. An escape character for matching characters used as wildcards has been introduced.
- Adding the "phone" field to supplier dataThis field has been added for its usefulness and the completeness of company information.
- Parameter "na-values" in GET product requestsThe possibility to include "not applicable" empty values (other than ETIM) marked as "-" (dash) or to omit them in the API response.
- Introduction of main keys in the API responsesIn responses to API requests of the GET type, main keys have been introduced to allow sending in the response not only the actual object of the request but also additional information (such as the parameters with which the request was handled). The "with-keys" query parameter is introduced temporarily, to replace the existing response format (without keys) with the target response format (with keys). The introduction of the query parameter with the default value "false" does not change the existing response format. However, it sensitizes the change and makes it possible to use the target answer format with the value "true". In the second stage, the "true" will become the default value, but the old response format will be available with the "false" value. In the third final stage, the "with-keys" query parameter will be deleted, and the response will always be generated with keys.
- New format of "Delete categories" requestThe response format of the "Delete categories" request has been unified with other DELETE requests.
- New request parameter "as-supplier"Some requests (for downloading or updating product data) have been equipped with a new "as-supplier" parameter. It gives the possibility to access product information "as a supplier", i.e. the access key is based on the pair: "supplier"-"supplierPid", instead of the main product identifier ("productId"). This allows reaching the product information as if it was accessed on a supplier’s account, i.e. where the main product identifier is "supplierPid".
- New response key "parameters"For the convenience of users, the responses to some requests have been equipped with information about the parameters used in the request. These include all correctly used parameters (passed explicitly and implicitly).
- ETIM version 9The latest version 9 of ETIM classification has been made available in the application and is handled by the API.
- New fields for product filtering: "relatedProductsLastModifiedDate" and "relatedProductsModifiedBy"Due to the recording of the date and the user who changes information on related products, two additional fields have been introduced for product filtering: the date of the last change of related products and the user who made the change.
- Change of the key names in the response of product PUT request: "deletedProductRelations" -> "deletedRelatedProducts", "createdProductRelations" -> "createdRelatedProducts"The previously used term "product relations" was not explicit and could be interpreted as "relations by attributes" or as "related products." For this reason, it was replaced by an unambiguous term: "related products".
- No more keys with empty values in GET responsesThe rule that elements with empty values are not returned in API responses has been generalized (exceptions to this rule have been removed).
- Moving product modification date information (key "lastModifiedDateByType") to the end of the GET responseInformation about the modification dates of each category of product data was moved to the end of the GET response, due to a large number of categories and their corresponding dates. Only the creation date and the general date of the last modification were left at the beginning of the GET response.
- Reporting incorrect filter keys when filtering productsThe handling of erroneous API queries has been changed. Errors in filter keys in API requests were previously ignored and responses were based only on correctly used keys. Now, API requests containing incorrectly used keys will not be processed and an error message will be returned.
- Adding the "Expiration date" field for product filteringAn additional field "expirationDate" can be used for product filtering. The full list of filterable fields is available in the "Product filtering" section.
- "etim-format" parameter in "Get specified product(s) data in a language-dependent version" requestThe new parameter "etim-format" allows you to change the format of the response of ETIM information. The "key-value" value allows you to get an existing, but the potentially incorrect format (an error occurred in the ETIM description in classes containing multiple occurrences of features with the same name). The "array" value however allows you to get the new, correct, and target response format. It is recommended to use the new version of the response format.
- Renaming of request parametersThe names of two parameters were changed, in which the underscore character was replaced by a dash: "etim_version" -> "etim-version" and "delete_products" -> "delete-products". The old names will be valid until 2022-12-09.
- "Read-only" modeOption to block product modifications. All PUT and DELETE requests are blocked and the "read-only" error message is returned. The "read-only" mode can be used in exceptional situations, such as urgent maintenance work or hardware failure of the main server and temporarily switching the application to the backup server.
- New date filtering type "in the last"In addition to the existing possibility of filtering by "range" of dates (from-to), it is now possible to filter by relative: "in the last n hours/days/months" etc.
- The parameter "only-ids" set by default to true in the "Product filtering" requestThe default setting of the "only-ids" parameter in the "Product filtering" request is now changed to "true". As a result, the default response to the request is also changed (a list of product identifiers is returned without their last modification dates). In order to get the response in the previous format, please use the "only-ids" parameter set to false. Note, that the "only-ids" parameter is marked as deprecated and will be removed in the future.
- The request "List of all identifiers of relations by attribute modified on or after a given date" becames deprecatedThis request will not be maintained in the future. Last modification dates of relations by attribute are currently available directly in the product information.
- 16 new fields for product filtering16 new fields can be used for product filtering. See "Product filtering" section in the documentation for the current list of filterable fields.
- Summary of changes in product relations added to the PUT request responseCompletion of the JSON response to the PUT request (update/write data of specified product) with information on related products (deleted and created relations with other products are reported respectively in the new JSON keys: "deletedProductRelations" and "createdProductRelations").
- Ability to assign products to relations by attribute in PUT API requestsA new endpoint that allows assigning products to relations by attributes, regardless of defining these relations.
- Alternative version for two existing requestsNew alternative versions for two requests have been introduced to replace the original requests in the future. During the 3-month transition period, both versions of the requests will be supported. "List of all IDs of products modified on or after a given date" will replace "List of all IDs of products" and "List of all identifiers of relations by attribute modified on or after a given date" will replace "List of all identifiers of relations by attribute". The new requests can filter products by modification date and return a list of IDs (without modification date) together with the total number of IDs returned. Old requests become "deprecated" and will be deleted after 3 months.
- New parameter for product filtering requestProduct filtering request has been equipped with a new parameter "only-ids" (by default it is set to "false" for now, which in case of omitting this parameter allows getting the same response as before). Setting this parameter to "true" allows getting a simplified answer containing only products IDs (without date of modification) and the total number of IDs returned. In the next stage (after 3 months) the default version of the "only-ids" parameter will be "true". After another 3 months, the parameter will be removed and the request will return only identifiers (without modification dates) and the total number of IDs returned.
- Removal of "json_unescaped" parameterAn unused and deprecated parameter has been removed.
- System attributesNew field in attribute definition: "permanent" (modification related to the introduction of system attributes).
- Attribute descriptionsNew multilingual field in attribute definition: "description" (modification related to the introduction of language-dependent attribute descriptions).
- New type of attribute: "select"The new select attribute allows you to define a set of allowed values that an attribute can take. Each predefined value has an identifier (unique within the attribute) and a translation in the languages used.
- New type of attribute: "text"New attribute of type text allows providing a text value that is language independent (useful for providing codes, symbols, etc.).
- Rename attribute type "A" (alphanumeric) to "M" (multilingual text)Due to the introduction of the text type attribute and to avoid confusion, the alphanumeric attribute type name has been changed to multilingual text.
- HTTP response status codesReporting of API request processing has been unified and enhanced. The status of the result ("200 OK" / "400 Bad Request" / "404 Not Found") is always shown directly in the HTTP response status code, and in the case of errors, the details can be found in JSON response ("errors" key).
- Product filtering by values of global attributesAll global attributes created by the user can be used to filter products. Filters set on alphanumeric attributes are language dependent (it is necessary to indicate which language should be used).
- Deprecated elements of RESTful APIDue to API development, some elements will no longer be used. The list of such elements is published with their date of validity. During the transition period they are still supported, but marked as deprecated. All implementations using such elements should be modified before they expire (either by replacing deprecated element with their respective successors or by using alternative request syntaxes).
- BuyersAbility to retrieve (GET) and manage (PUT/DELETE) information about product information recipients (buyers).
- product filter by category identifier
- unification of supplier and wholesaler accounts and API documentation
- extension of API messages (product filtering)
- attributes as product characteristics
- key change in the product labels filtering: "names" to "identifiers"
- range type of product attribute
- compatibility with the International Guidelines BMEcat ETIM v. 5.0
- restriction of attribute types (ETIM and BMEcat)
- synchronization triggers
- update/delete of label definitions
- update/delete of attribute definitions
- view/update/delete of supplier definitions (only wholesalers)
- ETIM version selection in product GET requests ("etim_version" parameter)
- extension of API messages (in case of errors)
- changing the default value of the "json_unescaped" parameter to "true"
- new "groupId" field in "etimDescription" (product GET requests)
- new "version" field in "etimDescription" (language-dependent version of product GET requests)
- WWW information of products
- WWW information of categories
- new parameter of GET requests: json_unescaped (specifies whether the application escapes multibyte Unicode characters as \uXXXX and escapes / as \/)
- validity dates for MIME
- SEO information of products
- SEO information of categories
- indication whether the global attribute is subject to synchronization ("forSynch" field)
- adding a "last modified date" group for filtering
- logical operator "OR" for filter in "last modified date" and "description completeness" groups