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.
A guide for errors
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.
List for OKAPI errors
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:
|
| 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). |
|
| 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. |
|
| 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. |
|
| 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. |
|
|
| 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. |
|
|
| 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 |
|
|
| 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. |
|
| fetch_wtlp_span | as query parameter | Customize the responded data with a WLTP span values for types. Example: fetch_wltp_span=true |
|
|
| 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 |
|
| 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 |
|
|
| 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 |
|
|
| 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. |
|
| Optional Query Parameter | with_optional_information | as query parameter | Customize the responded data with optional informations. |
|
| 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. |
|
|
| 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. |
|
|
| 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. |
|
|
| distinct | as query parameter | Customizes the response to make the response configuration buildable and distinct. |
|
|
| allow_change_of_basetype | as query parameter | Customizes the response to allow the change of the basetype. |
|
|
| allow_change_of_model | as query parameter | Customizes the response to allow the change of the model. |
|
|
| 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. |
|
|
| 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 |
|
|
| 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 |
|
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",
}