How we create uuids
We are using the uuid Version 5 which is a standard uuid calculated by a namespace and a name,
in order to provide the ability to calculate uuids in a deterministic way, utilising the
id/qualifiers of the former data tree.
UUID V5 offers different modes to calculate a uuid we are using the namespaceMode URL in order to calculate a root hash from the project's URL (https://productdata.vwgroup.com). This uuid will be the parentUUID for the first level tree branches of the data, which are the brands. Every brand's uuid will use the namespaceMode UUID, therefore using the root uuid as parentUUID and the legacyBrandId (e.g. 'V' for Volkswagen) as name in order to calculate the brand's uuid. This way we are also calculating the model's uuid (using the brand's uuid as parentUUID and the legacy modelId as name), the typeId (using the model's uuid as parentUUID and the legacy typeId as name in combination with the model year) and the optionId (using the model's uuid as parentUUID and the legacy optionId as name).
given a function that calculates version 5 uuid's:
The process to create the uuids:
We are using content negotiation. Do you?
All resources will contain a specific representation. Content negotiation determines whether the resource can be requested or provided in a specific representation. Therefore we will check every request whether the Accept header is set, and we can provide the desired representation. If the resource cannot provided in the requested representation the API will respond with a http status code 406 (Not Acceptable). If you omit the header we will fallback to the value application_json and therefore respond in json. Additionally all resource will respond with the provided representation within the header Content-Type.
If you want to get more information on content negotiation please visit the rfc specification.
We will update the data provided constantly. If you are storing references of our data on your side you can utilise the http ETag header to check whether the data has changed since your last request. All Catalog endpoints will respond with an ETag header which keeps a hash value of the data the resource contains. As soon as the data changes this hash will change. You can store the hash on your side and provide it as value of the If-None-Match header in every request. If you provide this header and the content has not changed, the resource will respond with a 304 (Not Modified) and no body. If the content has changed, it will respond with a 200 providing the requested response body, and the new ETag value within the header.
Additionally the Last-Update-Timestamps returns the date of the latest product data update. This could change even though the OKAPI response and the Etag Headers would be the same. For more information regarding data updates in OKAPI see Tracking the changes in Product Data.
If you want to get more information about entity tags please visit the rfc specification (3.11 Entity Tags).
No WLTP Data?
If you are not able to receive any WLTP Data there are a few things to consider.
You have to provide a buildable configuration. To assure that your configuration is buildable please take a look at how to check whether your configuration is buildable.
You have to provide a distinct configuration, though we are just able to calculate the values if the selection of options within the given configuration point out just one single vehicle. To assure that your configuration is distinct please take a look at how we define a distinct configuration.
Additionally there is the option that no WLTP Data is available for the requested configuration, which will be indicated by 204 (Not Found) response.
So what do we mean if we talk about a distinct configuration: If you provide a partial configuration, and the combination of options is buildable, there might be several options, on how a car could be build.
A distinct configuration defines enough options to make out just one vehicle. We will always try to autocomplete a partial configuration, but in order to identify a single buildable vehicle we need as many options as it takes that there is just one version of a vehicle left: The first example picture shows a buildable partial configuration on the left side, which could make out three different ways to complete a vehicle that could be ordered. The selection of the red hubcap in the second picture identifies the red vehicle definitely. Therefore the selection of the given option makes out a distinct configuration.