ECLASS Webservice

ECLASS Structure Elements and Mappings can be accessed via a RESTful Webservice as XML or JSON. A certificate is required for authentication, which can be acquired through the ECLASS Shop. The Webservice is provided by the ECLASS CDP.

ECLASS Releases have until now been solely delivered as sets of huge files containing a complete ECLASS release. Applications, however, often need only a subset of the ECLASS structure elements, e.g. a particular class with some of its properties and values - and they need so on demand. Therefore, ECLASS is now offering a RESTful Webservices, which allow to obtain self-contained classes, properties, units and mappings without the need to handle the complete fileset of an ECLASS XML release.

The ECLASS Download API XML supports retrieval of individual classes (Classification Class, Application Class, Aspect or Block) and properties by their IRDI.

The system returns a self-contained ECLASSXML 3.0 file for the requested structure element.

Self-contained means that not only the requested element itself but also its referenced elements are contained in the result.

Furthermore, the ECLASS Download API XML supports retrieval of units of measurement by their IRDI. Here also, the system returns a self-contained ECLASSXML 3.0 file for the requested structure element.

The RESTful API for the XML retrieval is documented in SwaggerHub. (https://app.swaggerhub.com/apis-docs/ECLASS_Standard/ECLASS_Download_XML/1.0.4)

As shown above, the Webservice is a function of the CDP. For the XML download, the defined endpoints must therefore be applied to the CDP URL "https://www.eclass-cdp.com/"

To retrieve a class via IRDI (e.g. 0173-1---ADVANCED_1_1#01-ADN862#010) the following URL is necessary:

eclass-cdp.com/xmlapi/v1/classes/0173-1---ADVANCED_1_1%2301-ADN862%23010 

Note: The # in the IRDI has to be URL encoded via %23

This URL can now be retrieved using a client, such as a browser.

Similarly, a property call works (e.g. 0173-1#02-AAS574#002):

eclass-cdp.com/xmlapi/v1/properties/0173-1%2302-AAS574%23002 

The XML-API was improved and extended. Therefore, a new version with breaking changes was necessary. The RESTful API for the XML retrieval in V2 is documented in SwaggerHub. (https://app.swaggerhub.com/apis-docs/ECLASS_Standard/ECLASS_Download_XML/2.0.0)
In the following chapter a detailed list of changes is described.

XML Changelog from V1 to V2

ECLASS Download API XML v2.0.0 is a major upgrade featuring improved XML format support, enhanced internationalization, and new reverse lookup capabilities.

Breaking Changes

1. API Endpoint URLs
All API endpoints have been updated from version 1 to version 2:
/xmlapi/v1/*  →  /xmlapi/v2/*
**Action Required:** Update all API calls to use the new v2 base path.

2. XML Format Upgrade
The API now returns **ECLASS XML 5.0** (previously 3.0).
- **Old Content-Type:** `application/x.eclass.v3+xml`
- **New Content-Type:** `application/x.eclass.v5+xml`
**Action Required:** Update XML parsers to support ECLASS XML 5.0 format.

3. No self-contained ApplicationClasses in ClassificationClass requests 
When retrieving a ClassificationClass of level 4 with `includeAC=true` in Version 1 the ApplicationClass was returned as “self-contained” element including all Properties, Values and necessary structure elements.
In V2 the ApplicationClass is returned as well, but without Properties, Values, and structure elements. This massively reduces response size. An Application must load ApplicationClass details separately if needed or do a separate request for the specific ApplicationClass via GET /xmlapi/v2/classes/{applicationClassIRDI}.

New Features

1. Multi-Language Support
All endpoints now support the `Accept-Language` header for localized content.
e.g. Accept-Language: de-DE, en-US
Default language: `en-US`

2. Deprecated Element Access
New `Deprecated` header allows controlled access to deprecated elements.
e.g. Deprecated: true
- `false` (default): Returns 404 for deprecated elements
- `true`: Returns deprecated elements normally

3. License-Only Mode
New `licenseOnly` query parameter for efficient license tracking without downloading content.
e.g. GET /xmlapi/v2/classes/{irdi}?licenseOnly=true

4. Reverse Lookup Endpoint (NEW)
List all Classification Classes assigned to an Application Class.
e.g. GET /xmlapi/v2/classifiedAs/{irdi}

The examples from above now would be:

eclass-cdp.com/xmlapi/v2/classes/0173-1---ADVANCED_1_1-01-ADN862-010 
eclass-cdp.com/xmlapi/v2/properties/0173-1-02-AAS574-002 

In addition to a fundamentally different serialization of the ECLASS structure elements using JSON, the JSON API also extends the functionalities in contrast to the XML retrieval.
In general, specific endpoints exist for each structure element type. In addition, there is the possibility of a list retrieval for each structure element type. In this list retrieval it is also possible to search for elements via the preferred name.
The RESTful API for the JSON retrieval is documented in SwaggerHub. (https://app.swaggerhub.com/apis-docs/ECLASS_Standard/ECLASS_Download_JSON/1.4.2)

The examples for the XML API lead here accordingly to the following URLs:

To retrieve an Application Class via IRDI (e.g. 0173-1---ADVANCED_1_1#01-ADN862#010) the following URL is necessary:
eclass-cdp.com/jsonapi/v1/applicationClasses/0173-1---ADVANCED_1_1%2301-ADN862%23010 

Similarly, a property call works (e.g. 0173-1#02-AAS574#002):
eclass-cdp.com/jsonapi/v1/properties/0173-1%2302-AAS574%23002

Due to several extensions of ECLASS, user Feedback and consistent improvements it was necessary to adapt the JSON API with breaking changes. The RESTful API for the JSON retrieval in V2 is documented in SwaggerHub[DB1] . In the following chapter a detailed list of changes is described.

JSON Changelog from V1 to V2

Breaking Changes

1. API Path Update
All endpoints have changed from `/jsonapi/v1/` to `/jsonapi/v2/`

2. Enum Format Changes
Property Type
| v1.4.2 | v2.0.4 |
|--------|--------|
| `"non-dependent"` | `"NONDEPENDENT"` |
| `"dependent"` | `"DEPENDENT"` |
| `"condition"` | `"CONDITION"` |

Property Data Type
| v1.4.2 | v2.0.4 | Notes |
|--------|--------|-------|
| `"Axis 1D"` | `"AXIS1D"` | |
| `"Axis 2D"` | `"AXIS2D"` | |
| `"Axis 3D"` | `"AXIS3D"` | |
| `"Boolean"` | `"BOOLEAN"` | |
| `"Date"` | `"DATE"` | |
| `"Integer (count)"` | `"INTEGERCOUNT"` | |
| `"Integer (currency)"` | `"INTEGERCURRENCY"` | |
| `"Integer (measure)"` | `"INTEGERMEASURE"` | |
| `"Rational (count)"` | `"RATIONALCOUNT"` | |
| `"Rational (measure)"` | `"RATIONALMEASURE"` | |
| `"Real (count)"` | `"REALCOUNT"` | |
| `"Real (currency)"` | `"REALCURRENCY"` | |
| `"Real (measure)"` | `"REALMEASURE"` | |
| `"Reference"` | `"REFERENCE"` | |
| `"String"` | `"STRING"` | |
| `"String (translatable)"` | `"STRINGTRANSLATABLE"` | |
| `"Time"` | `"TIME"` | |
| `"Timestamp"` | `"TIMESTAMP"` | |
| `"URL"` | `"URL"` | |
| `"File"` | `"FILE"` | |
| `"Blob"` | `"BLOB"` | |
| *(n/a)* | `"URN"` | **NEW in v2.0.4** |

Value Data Type
| v1.4.2 | v2.0.4 | Notes |
|--------|--------|-------|
| *(n/a)* | `"BOOLEAN"` | **NEW in v2.0.4** |
| `"Date"` | `"DATE"` | |
| `"Integer (count)"` | `"INTEGERCOUNT"` | |
| *(n/a)* | `"INTEGERMEASURE"` | **NEW in v2.0.4** |
| *(n/a)* | `"INTEGERCURRENCY"` | **NEW in v2.0.4** |
| `"Rational (count)"` | `"RATIONALCOUNT"` | |
| *(n/a)* | `"RATIONALMEASURE"` | **NEW in v2.0.4** |
| `"Real (count)"` | `"REALCOUNT"` | |
| `"Real (measure)"` | `"REALMEASURE"` | |
| `"Reference"` | `"REFERENCE"` | |
| `"String"` | `"STRING"` | |
| `"Time"` | `"TIME"` | |
| `"Timestamp"` | `"TIMESTAMP"` | |

Value List Data Type
| v1.4.2 | v2.0.4 |
|--------|--------|
| `"Boolean (yes/no)"` | `"BOOLEAN"` |
| `"Date"` | `"DATE"` |
| `"Integer (count)"` | `"INTEGERCOUNT"` |
| `"Integer (currency)"` | `"INTEGERCURRENCY"` |
| `"Integer (measure)"` | `"INTEGERMEASURE"` |
| `"Rational (count)"` | `"RATIONALCOUNT"` |
| `"Rational (measure)"` | `"RATIONALMEASURE"` |
| `"Real (count)"` | `"REALCOUNT"` |
| `"Real (currency)"` | `"REALCURRENCY"` |
| `"Real (measure)"` | `"REALMEASURE"` |
| `"Reference"` | `"REFERENCE"` |
| `"String"` | `"STRING"` |
| `"Time"` | `"TIME"` |
| `"Timestamp"` | `"TIMESTAMP"` |

3. Schema Field Changes
Property schema enhancement:
- New field: `singleLevelProperties` (array) - enhanced level type handling
- New schema: `definedLevel` - structured level definitions with property references
- Existing `definedLevels` field remains for backward compatibility
- Field name typo corrected: `singeLevelProperties` → `singleLevelProperties`
ValueList schema change:   `quantities` (array) → `quantity` (single object)
ValueData schema addition: New field: `quantity` (optional)

4. Multilingual content structure change (excluding Synonyms & Keywords):
- text fields `preferredName`, `shortName`, `definition`now return arrays instead of language-map objects**
- Translation Quality Level (TQL) (Native, Translator, DeepL, Auto, ECLASS Expert, etc.) added to track translation source/quality
e.g.
v1.4.2: `{"en-US": "text", "de-DE": "Text"}` (object with language keys)
v2.0.4: `[{language: "en-US", label: "text", translationQualityLevel: "Native"}, ...]` (array of objects)

New Features

New Endpoints
- `GET /jsonapi/v2/aspectTypes` - List of Aspect Types
- `GET /jsonapi/v2/aspectTypes/{irdi}` - Single Aspect Type
- `GET /jsonapi/v2/applicationClasses/{irdi}/classifiedAs` - Classification Classes for Application Class
- `GET /{irdi}` - Generic gateway
This endpoint runs under subdomain api.eclass-cdp.com only
e.g. api.eclass-cdp.com/0173-1-02-AAC895-008

A full Accept-Language Header is “en-US,de-DE,fr-FR,es-ES,it-IT,pt-PT,pl-PL,nl-NL,ru-RU,ro-RO,bg-BG,zh-CN,cs-CZ,hu-HU,ja-JP,ko-KR,sk-SK,sv-SE,zh-TW,th-TH,tr-TR,fi-FI,da-DK,et-EE,el-GR,lv-LV,lt-LT,sl-SI,uk-UA,id-ID,nb-NO”

Please find in the following a short introduction to the ECLASS Webservice: ECLASS WEBSERVICE - Retrieval of ECLASS content via Webservice