Skip to Content
Product Information

SAP Digital Vehicle Hub API to create or update vehicles

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

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

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%20Overview

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:

Client ID uaa.clientid
Client Secret uaa.clientsecret
Authentication URL uaa.url Example: https://<subdomain>.authentication.eu10.hana.ondemand.com
Application URL for REST API endpoints.service-url Example: https://dvh-service.cfapps.eu10.hana.ondemand.com
Application URL for OData API endpoints.odata-service-url Example: https://dvh-srv.cfapps.eu10.hana.ondemand.com

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%3A%20Get%20access%20token

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%20Vehicle%20in%20SAP%20Digital%20Vehicle%20Hub

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%20with%20planned%20maintenance%20data

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

Be the first to leave a comment
You must be Logged on to comment or reply to a post.