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.volkswagenag.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.volkswagenag.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.


Set classification for request

In OKAPI, it is possible to specify, which kind of request is made. A distinction is made between "ONLINE" and "BATCH" requests.
If nothing is specified, it will be classified as "ONLINE".
The classification can be set by adding the Header "OKAPI-PROCESSING-TYPE" to the request. By setting the Header to "BATCH" (Upper and lower case will be ignored) the request will be classified as "BATCH".
If a low response time has no priority, it should be classified as "BATCH" (for example requests to import data to cache) otherwise it should be "ONLINE" and will be prioritised over "BATCH" requests to provide the best possible response time.

OKAPI Keywords

There are some keywords in OKAPI, which can be part of the request. In the following table you will find the keywords with a small explanation and where you can use them in your requests:

Topic Keyword Part of the Request Description Endpoints
Product Data key product_data_key as query parameter Customize the responded data with a specific product data key.
Example: product_data_key=CONSUMER_GROUP
every endpoint
Country country_code if required in URL (e.g. /v3/catalog/{country_code}/brands) A supported country as (ISO 3166-2) country code.
Example: country_code=DE
every operations endpoint, every catalog endpoint except:
  • /countries
  • /brands
  • /brands/{brand}/countries
Language language_code as query parameter and in request body Returns the result in a desired language (ISO 639-1). When not set, the default language of the given country code (ISO 3166-2) will be used.
Example: language_code=en
every endpoint
Brand brand_code if required in URL (e.g. /v3/brands/{brand}/countries), in request body (as part of the configuration) A supported brand as a brand code (ISO 3166-2).
  • /brands/{brand}/countries
  • /brands/{brand}
  • /brands/{brand}/models
  • /brands/{brand}/types
  • /brands/{brand}/types/{type}/base_configuration (GET and POST)
  • /brands/{brand}/types/{type}/model_year/{model_year}/base_configuration
  • /brands/{brand}/language
brand_id if required in URL (e.g. /v3/brands/{brand}/countries), in request body (as part of the configuration) The UUID of a supported brand. same as brand_code
brand_description in request body (as part of the configuration) The description of the brand. every operations endpoint (optional)
Model model_code if required in URL (e.g. /v3/catalog/{country_code}/models/{model}), in request body (as part of the configuration) The model as model code.
  • /models/{model}
  • /models/{model}/types
model_id if required in URL (e.g. /v3/catalog/{country_code}/models/{model}), in request body (as part of the configuration) The UUID of a model. same as model_code
model_description In request body (as part of the configuration) The description of the model. every operations endpoint (optional)
Type basetype_code in request body (as part of the type) The basetype code of the type.
  • /brands/{brands}/types
  • /brands/{brand}/types/{type}/base_configuration (GET and POST)
  • /brands/{brand}/types/{type}/model_year/{model_year}/base_configuration
  • /models/{model}/types
  • /types
  • /types/{type}
  • /types/{type}/model_year/{model_year}
  • /types/{type}/options
  • /types/{type}/model_year/{model_year}/options
every operations endpoint with a configuration which has a type in the options list (optional)
code if required in URL (e.g. /v3/catalog/{country_code}/types/{type}), in request body (as part of the configuration) The type as type code.
  • /brands/{brand}/types/{type}/base_configuration (GET and POST)
  • /brands/{brand}/types/{type}/model_year/{model_year}/base_configuration
  • /types/{type}
  • /types/{type}/model_year/{model_year}
  • /types/{type}/options
  • /types/{type}/model_year/{model_year}/options
every operations endpoint with a configuration which has a type in the options list (optional)
id if required in URL (e.g. /v3/catalog/{country_code}/types/{type}), in request body (as part of the configuration) The UUID of a type. same as type code
extensions in request body (as part of the type) The extension of a type. same as basetype_code
possible_extension_replacements as query parameter Customize the responded data with the possible replacements for each extension if available.
  • /brands/{brands}/types
  • /models/{model}/types
  • /types/{type}
  • /types/{type}/model_year/{model_year}
  • /types/{type}/options
  • /types/{type}/model_year/{model_year}/options
Model Year modelyear_code in request body (as part of the type object) The model year as modelyear_code. same as basetype_code
model_year if required in URL (e.g. /v3/catalog/{country_code}/types/{type}/model_year/{model_year}) The modelyear as request parameter, written as code.
Example: model_year=MODELYEAR:2022
  • /brands/{brand}/types/{type}/model_year/{model_year}/base_configuration
  • /types/{type}/model_year/{model_year}
  • /types/{type}/model_year/{model_year}/options
every operations endpoint with a configuration which has a type in the options list (optional)
Custom Conditions custom_conditions in request body (as part of the configuration object) The custom conditions for the configuration as an object, consisting of a maximum_price object and options object. every operations endpoint except GET /marketing_code
maximum_price in request body (as part of the custom_conditions object) Customize the responded data with a maximum price as a condition. same as custom_conditions
one_of in request body (as part of the custom_conditions object) Customize the responded data with one_of conditions for multiple option lists. There can be multiple lists in the custom_conditions.options field. same as custom_conditions
none_of in request body (as part of the custom_conditions object) Customize the responded data with a none_of condition for an option lists. same as custom_conditions
WLTP round as query parameter Customize the responded data to specify if interpolation values should be rounded.
  • /wltp
fetch_wtlp_span as query parameter Customize the responded data with a WLTP span values for types.
Example: fetch_wltp_span=true
  • /brands/{brands}/types
  • /models/{model}/types
  • /types
  • /types/{type}
  • /types/{type}/model_year/{model_year}
Full Configuration extended_order as query parameter Customize the responded data to return extended options of the complete configuration like e.g. extensions, market and version.
Example: extended_order=true
  • /resolve
  • /order (deprecated)
extended_with as query parameter Customize the responded data to specify which additional data should be returned. Multiple fields are possible.
Example: extended_with=technical_data+technical_attributes
  • /order
selected_technical_attributes as query parameter Customize the responded data to return only selected technical attributes.
Example: selected_technical_attributes=MASS-OPTIONS-FITTED-REAR+MASS-VEHICLE-DECLARED+3.5.1.0+NEDC-EEC+3.4.1.1.2
  • /order
Option options in request body (as part of configuration) The list of options belonging to the configuration. same as custom_conditions
is_standard in request body (as part of an option in options array) Indicates if the option belongs to the standard equipment. same as custom_conditions
is_visible in request body (as part of an option in options array) Indicates if the option should be visible. same as custom_conditions
classification in request body (as part of an option in options array) The classification of an option. The classifications are STANDARD_EQUIPMENT, OPTIONAL_EQUIPMENT and LOCAL_EQUIPMENT. same as custom_conditions
is_packet in request body (as part of an option in options array) Indicates if the option is a package. same as custom_conditions
packet_content in request body (as part of an option in options array) The packet content is a list of options contained in this package option. same as custom_conditions
tag_groups in request body (as part of an option in options array) The tag groups is a list of tags with addiotional informations. same as custom_conditions
tags in request body (as part of an option in options array) Tags is a list of tags of belonging to the same tag group. same as custom_conditions
tag_type in request body (as part of an option in options array) The tag_type indicates the type of the tag. same as custom_conditions
category in request body (as part of an option in options array) Indicates the category of an option. same as custom_conditions
Marketing Code marketing_code if required in URL (e.g. /v3/operation/{country_code}/marketing_code/{marketing_code}) The marketing code for loading a configuration.
  • /marketing_code (GET)
Optional Query Parameter with_optional_information as query parameter Customize the responded data with optional informations.
  • /configure
nice_to_have as query parameter Parameter to list the nice to have options of the configuration. When solving a configuration, they have a lower priority than the preferred_options and options in the configuration, and will only be retained when a configuration with them and the preferred and options in the configuration.
  • /solve
  • /solutions
count as query parameter Customizes the maximum number of solutions to be returned. The number of solutions may be less than the count if no more solutions are possible. Currently maximum 5 solutions are requestable, this may change at any time.
  • /solve
  • /solutions
  • /marketing_code (GET)
preferred_options as query parameter Customizes the response with options like in a one of options list. The given options must be without any relation to a family or relation to each other (AND conjunction). Same weight as one_of. It is not guaranteed that the options are part of a solution.
  • /solutions
distinct as query parameter Customizes the response to make the response configuration buildable and distinct.
  • /solutions
  • /marketing_code (GET)
allow_change_of_basetype as query parameter Customizes the response to allow the change of the basetype.
  • /solutions
  • /marketing_code (GET)
allow_change_of_model as query parameter Customizes the response to allow the change of the model.
  • /solutions
  • /marketing_code (GET)
extend_with as query parameter Customizes the response to with the given list of domains (e.g. CARLINE, SALESGROUP), if options belonging to these domains are available for the solution candidate.
  • /solutions
  • /marketing_code (GET)
Prefix MODEL in model code (see model_code) The prefix MODEL is part of the model_code in OKAPI.
Example: MODEL:30100_30100
same as model_code
TYPE in type code (see type_code) The prefix TYPE is part of the type_code in OKAPI.
Example: TYPE:3H947Z-GYORYOR-GYTZYTZ
same as type_code
BASETYPE in basetype code (see basetype_code) The prefix BASETYPE is part of the basetype_code in OKAPI.
Example: BASETYPE:3H947Z
same as basetype_code
MODELYEAR in model year (see model_year) and model year code (modelyear_code) The prefix MODELYEAR is part of the model_year / modelyear_code in OKAPI.
Example: MODELYEAR:2022
same as model_year and modelyear_code
COLOR_INTERIEUR in options as category of an option and in the code of an interieur color option The prefix COLOR_INTERIEUR is part of the options code when the option is a interieur color. Also the prefix is the category of an interieur color option.
Example: COLOR_INTERIEUR:OH
same as custom_conditions
COLOR_EXTERIEUR in options as category of an option and in the code of an exterieur color option The prefix COLOR_EXTERIEUR is part of the options code when the option is an exterieur color. Also the prefix is the category of an exterieur color option.
Example: COLOR_EXTERIEUR:P8P8
same as custom_conditions
PACKET in options as category of an option and in the code of a packet option The prefix PACKET is part of the options code when the option is a packet. Also the prefix is the category of a packet option.
Example: PACKET:YOR
same as custom_conditions
SALESGROUP in the code of a tag in the tags array The prefix SALESGROUP is part of the code of an sales group tag.
Example: SALESGROUP:30450
same as custom_conditions
VERSION in options as category of an option and in the code of a version option The prefix VERSION is part of the options code when the option is a version. Also the prefix is the category of a version option.
Example: VERSION:1
  • /solutions
  • /marketing_code (GET)
  • /order
MARKET in options as category of an option and in the code of a market option The prefix MARKET is part of the options code when the option is a market. Also the prefix is the category of an market option.
Example: MARKET:X0A
  • /solutions
  • /marketing_code (GET)
  • /order


Accept and Encoding

Accept:
The Accept header indicates which media types the client expects as a response for this request. The media type consists of two parts (main type and subtype). Both are separated from each other by a slash. The * indicates that no file type is preferred.

Example for Accept:
Accept: */*

Accept-Endcoding:
With the help of the Accept-Encoding header, the client indicates which encoding methods it understands or can process. OKAPI uses the procedures gzip, deflate and br.

Example for Accept-Endcoding:
Accept-Endcoding: gzip, deflate, br



OKAPI Timeout

The OKAPI-Timeout header can be sent in requests in order to define the timeframe in which OKAPI should respond. Otherwise, an error would be returned. The duration needs to be defined in milliseconds.

Example for OKAPI Timeout:
OKAPI-Timeout: 100

An example error from an operations request, where the timeout was exceeded: (More Information about errors)

{
"error_code": "204000089",
"error_message": "request timed out",
}