The Guide


FAQ

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:

uuidv5(namespaceMode::NameSpaceModeEnum, parentUUID::UUID, name::String) uuid:UUID {...}

The process to create the uuids:

var root UUID = uuidv5(nsMode.URL, null, 'https://productdata.vwgroup.com')
var brand UUID = uuidv5(nsMode.UUID, root, 'V')
var model UUID = uuidv5(nsMode.UUID, brand, '30450_31600')
var type UUID = uuidv5(nsMode.UUID, model, 'TYPE:1222AV-GPKBPKB-GZRGZRG-GPAFPAF-2018')
var option UUID = uuidv5(nsMode.UUID, model, 'FLS:8K1')

406?

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 be 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. In case of your client sends charset in content-type header, e.g. .NET-HTTP-Clients, 406 will also be sent as an answer.

If you want to get more information on content negotiation please visit the rfc specification.

Data updates?

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.

Distinct?

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.

What does this error mean?

In OKAPI, an error has always an error code and an error message which explains why the request could not be satisfied. In some cases, a few details will also be displayed e.g. which code or id is the problem. There can be many reasons, why a request leads to an error. For example, an invalid model code in your request can lead to a “model not found” error because OKAPI does not know this model code. Also, an formatting error in your body of the request can lead for example to an “invalid payload” error. Below you can see an example error:

{
"error_code": "151000068",
"error_message": "the given option_id is either invalid or does not belong to the specific model",
"error_details": [
"ada9fd41-3483-551e-a461-c5611d4sdasd01b54"
]
}

Some endpoints (e.g. order or marketing_code) only can be requested with a distinct configuration. In those cases make sure to check the configuration before sending the request. In case of a non-distinct or not buildable configuration, you can use OKAPI to heal your configuration. Healing configurations can be done in various ways in OKAPI. For more information, read about the endpoints resolve and recover in the guide.

Some errors in OKAPI are coming from other services, which are used by OKAPI. These errors might appear, but they are rare. In this case, OKAPI will display an “subservice error”. When the error occurs, retry your request after 5 sec, 10 sec, 1 min and 5 min. If the problem still happen after trying it several times, make sure you contact the OKAPI support.
For a good analysis of your problem, please submit the complete request, which includes the request URL, the request body and the OKAPI error response.

{
"error_code": "101000005",
"error_message": "subservice error"
}

When experiencing timeouts of the API try to resend the request 5-10 times. If you still receive a timeout after several retries please reach out to the support.