SAP has recently launched the new product
SAP Digital Vehicle Hub.
This blog post is part of a blog series. The
initial blog post comprises a general introduction to SAP Digital Vehicle Hub and an overview about the other topics of this blog series
In this blog post we will focus on the
SAP Digital Vehicle Hub API to create or update vehicles.
This blog post briefly covers the general architecture and the API access options, explains the authentication flow, and gives some example API requests to create and update a vehicle object.
Architecture
The SAP Digital Vehicle Hub is running on the SAP Cloud Platform. An overview about the architecture is given in the following picture:

SAP Digital Vehicle Hub Architecture
The APIs can be used to connect to various systems, such as SAP ERP systems, distributor systems, dealer systems or any other system. There are two APIs using HTTP requests:
- REST API – APIs to create, update, read and search complete vehicle information (both configuration and transactional information),
- OData API – fine granular APIs to maintain transactional information of a vehicle.
The documentation of the APIs can be found on the
SAP API Business Hub:

SAP API Business Hub
While the user accesses the SAP Digital Vehicle Hub application’s SAP Fiori Launchpad in any web browser, technical access is done via the API endpoint:

API Overview
The API endpoints for SAP Digital Vehicle Hub on the SAP Cloud Platform are passive, i.e. no active push or pull possible, it can only receive requests.
Authentication
The authentication for the API is done via
OAuth2 client credentials grant with tokens. The bearer/access tokens are used to grant access to the APIs. This is described in more detail in the
developer guide.
The credentials can be found on the Cloud Foundry enabled SAP Cloud Platform Subaccount, where the SAP Digital Vehicle Hub application is subscribed. Follow this click-path to find the Service Key:
- SAP Cloud Platform Subaccount
- Spaces
- “Name of the space” (create if not yet existing)
- Service Instances
- “Name of the service instance” (create if not yet existing)
- Service Keys: “Name of the service key”
- Menu: view or download
The Service Key contains the authentication information:
Use the information from the Service Key to get a token with the following POST request (add “/oauth/token” to the Authentication URL to request a token):
POST <authentication url with /oauth/token>
Headers:
Content-Type = <application/x-www-form-urlencoded>
Parameters:
grant_type = client_credentials
Body:
client_id = <client_id>
client_secret = <client_secret>
The client ID and client secret are also accepted in the HTTP Basic Auth header.
The API tool
Postman can be used to test API requests. In the following, you can see a screenshot of a POST request used to obtain an access token in Postman:

Postman: Get access token
It is also possible to use the OAuth2 password flow to obtain a token. Username and password (of the user for the application launchpad) can be provided in addition to the client credentials. This is described in the
developer guide.
The response body should look like this:
{
"access_token": "<string>",
"token_type": "bearer",
"expires_in": <expiration time>,
"scope": "<list of scope items>",
"jti": "<JWT ID>"
}
Use the
access_token string from the authentication response body for subsequent requests to the API endpoint in the header as Bearer token by adding the following to the header:
Bearer access_token string
API request for vehicles
For a comprehensive list of all available requests, refer to the
SAP API Business Hub and the
developer guide. In the following, some exemplary API requests are described.
API endpoint
The API endpoint follows this convention:
https://<application_url>/<service_endpoint>;
In the following, these placeholders are used for the respective API endpoints
{{dvh_REST_api_endpoint}} for the REST API
{{dvh_OData_api_endpoint}} for the OData API
Create Vehicles
When creating a new vehicle, many optional elements can be part of the request body. The minimal mandatory parameters required are the External ID and the description. This is described in more detail on the
SAP API Business Hub in the Vehicle section of the “Maintain Vehicle” documentation.
Example request with a very simple vehicle create request:
POST {{dvh_REST_api_endpoint}}/vehicle
With the following body:
{
"vehicleIdentifyingElements": {
"externalID": "RIN20161248867"
},
"description": [
{
"short": "RinSpeed Vehicle"
}
]
}
The response body should look like this:
{
"vehicleIdentifyingElements": {
"externalID": "RIN20161248867",
"id": "1234GUID1234GUID1234GUID1234GUID",
}
}
The created vehicle in the SAP Digital Vehicle Hub has no additional information besides the external ID and the description:

Simple Vehicle in SAP Digital Vehicle Hub
Enhance the create vehicle request with additional information in the body, e.g. the VIN (Vehicle Identification Number) and a vehicle model:
{
"vehicleIdentifyingElements": {
"externalID": "RIN20161248868",
"vin": " WBRIN5L51050G0914"
},
"description": [
{
"short": "RinSpeed Vehicle"
}
],
"modelSpecification": {
"modelExternalID": "Metro-Snap-2020"
}
}
A description of the SAP Digital Vehicle Hub data model including an example of a vehicle object with a vehicle model is given in the following blog post:
SAP Digital Vehicle Hub Data Model
Search for Vehicles
The vehicle search request returns results for given search values, it is also possible to search for vehicles with specific attributes. This is described in more detail on the
SAP API Business Hub in the VehicleSearch section of the “Maintain Vehicle” documentation.
Example request with a simple search for vehicles with a specific model:
PUT {{dvh_REST_api_endpoint}}/vehicleSearch
With the following body:
{
"top": 10,
"skip": 0,
"modelExternalID": "Metro-Snap 2020"
}
With the top and skip parameters allowing for paging of the search results, with this request the top 10 results without skipping any results are returned. To loop through all results, the response body contains a count value.
Retrieve Vehicle Information
The complete details of a vehicle can be retrieved via the API. This is described in more detail on the
SAP API Business Hub in the Vehicle section of the “Maintain Vehicle” documentation.
Example request to read a vehicle by external ID:
GET {{dvh_REST_api_endpoint}}/vehicle?externalID=RIN20161248868
In order to include more details in the response body, bool parameters can be added to the request, e.g. for service contract details:
GET {{dvh_REST_api_endpoint}}/vehicle?externalID=RIN20161248868&serviceContractRequiredIndicator=true
Update or add Vehicle Information
To update vehicle objects, a PATCH request can be used. This changes only the patched details of the vehicle objects while letting the other details unchanged. This is described in more detail on the
SAP API Business Hub in the Vehicle section of the “Maintain Vehicle” documentation.
Example request to update the VIN of an existing vehicle, identified by the external ID:
PATCH {{dvh_REST_api_endpoint}}/vehicle?externalID=RIN20161248868
With the following body:
{
"vehicleIdentifyingElements": {
"vin": "WBRIN5L51050G0915"
}
}
The
OData API can also be used to create or update vehicle information, for example adding a planned maintenance interval. This request is described in more detail on the
SAP API Business Hub in the Vehicle Planned Maintenance Interval section of the “Maintain Vehicle Association” documentation, other OData requests are listed there as well.
Example request to create a planned maintenance interval via OData API, identified by the GUID:
POST {{dvh_OData_api_endpoint}}/vehiclePlannedMaintenanceInterval/plannedMaintenanceInterval
With the following body:
{
"vehicleID": "1234GUID1234GUID1234GUID1234GUID",
"typeCode": "INSP",
"nextServiceDate": "2022-01-01",
"nextServiceCounter": "30000",
"uomCode": "1"
}
The vehicle is updated with the planned maintenance interval data:

Vehicle with planned maintenance data
API resources and documentation
Further API resources and documentation with more details can be found on the API Business Hub and in the SAP Digital Vehicle Hub Developer Guide on the SAP Help Platform.
SAP API Business Hub https://api.sap.com/package/SAPDigitalVehicleHub
Developer Guide with API information and API documentation
https://help.sap.com/doc/f6514e45f8dd48878d221cfb5616c157/latest/language/Developer%20Guide.pdf on the SAP Help Platform (version 1.0 as of writing of this blog post).
Conclusion
This blog post briefly covered the general architecture and the API access options of the SAP Digital Vehicle Hub, explained the authentication flow, and showed some example API requests to create and update a vehicle object.
Have a look on the other post of this blog post series, all linked from the
initial blog post or ask a question in the
Intelligent Asset Management Community.
More Information
SAP Digital Vehicle Hub Product homepage:
SAP Digital Vehicle Hub
SAP Digital Vehicle Hub Help Portal:
https://help.sap.com/viewer/product/SAP_DIGITAL_VEHICLE_HUB
Community homepage (IAM):
https://community.sap.com/topics/intelligent-asset-management