.svg){kind=small}
After downloading High Mobility's Postman Collection and the custom environment from the Client Certificate tab on the application’s page in the Hplatform – you will be able to consent to the sharing of your emulated car’s data and begin accessing its data via the Auto API.
Step 1: Download the Postman Collection
We have created a Postman Collection which includes requests for each of our APIs. In addition, we have created downloadable, pre-configured environments on each App’s page, which contain environmental variables specific to the user and to each application, and custom Auth URIs, which includes the correct parameters to start the consent flow. After importing the Postman Collection and environment and completing the consent flow, gathering data from a vehicle is as simple as obtaining an access token, selecting an API and clicking “send”.
Download the Postman Collection
Step 2: Importing the Postman Collection
The High Mobility REST Auto API collection will appear on the left side. It includes all of our APIs, each configured with the relevant method and request URI. For instance, the “Get vehicle doors state” API uses the GET method, and the request URI is /doors.
Step 3: Importing the environmental variables
In order to use the APIs in the Collection, it is necessary to configure the environmental variables, obtain an authorization code, and exchange it for an access token. To simplify this process, we provide downloadable versions of both the Collection and customized environment on every application’s page; the environment is created from information available on the “User Settings” page and the application’s page.
Once imported you will see a confirmation message on the lower right corner of the screen and the custom environment will look something like the image below.
Step 4: Getting an Authorization Code and an Access Token
In order for an application to gather data from an emulated car, the API request must include an OAuth Access Token as a credential.
Important distinction: An authorization code and an access token are different things:
Authorization code: Temporary code which the application owner exchanges for an access token. The code is obtained from the authorisation server after the car owner starts the consent flow, sees which data points the application would like to read, and approves the request. The authorization code is not an access token. The only thing you can do with it is exchange it for an access token. (adapted from https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/ )
Access token: Access tokens are the thing that applications use to make API requests on behalf of a user. The access token represents the authorization of a specific application to access specific parts of a user’s data. (from https://www.oauth.com/oauth2-servers/access-tokens/)
An authorization code is obtained and then exchanged for an access token through the following process: The “car owner” – in this case, the developer who created the emulator – completes the consent flow in a browser and authorizes the sharing of car data with the app. An authorization code is then generated on the HIGH MOBILITY servers and provided to the developer as a parameter in the redirect URI when the user is passed back to the application. In this example, the authorization code is then manually added to the environmental variables in Postman and is then exchanged for an access token via the “Code -> Access token” API call. The access token is added to the environment automatically and used during subsequent API calls.
Starting the consent flow to obtain an authorization code
Inside the High Mobility platform – on the Postman Config tab of each application’s page – there is a preconfigured Auth_URI which includes the CLIENT_ID, APP_ID, and REDIRECT_URI as parameters. Copy the Auth_URI and paste it in the address bar of a browser to start the consent flow.
After the consent flow is complete, the car owner will be redirected to a new URL with the authorization code as a parameter in the address bar. The URL in the address bar will now look something like this:
http://hm-postman.local/?code=698c8065-f8c9-4700-8e75-5c6c4f91f540&state=&theme=
Copy the authorization code string, found between “code=” and “&” in your address bar after completing the consent flow. The correct portion of the URL is above in Italic.
Step 5: Paste the authorization code into the Postman environment
Paste your authorization code (it should look similar to 698c8065-f8c9-4700-8e75-5c6c4f91f540 from the previous step) into the CURRENT VALUE column of the OAUTH_CODE row of the Postman environment.
Step 6: Exchange the authorization code for an Access Token
Once the code has been manually copied and added to the Postman environment, obtaining an access token is as simple as sending the Code -> Access Token request found in the Postman Collection; the access token will automatically be added to the environment after the request.
That’s it! You are ready to start gathering data from the vehicle via the Auto API.
Step 7: Calling the Auto API
Calling the Auto API is as simple as selecting a request and clicking “send”. The JSON responses are easily readable. It is possible to send POST requests to the vehicle as well; there are POST requests which turn the ignition on or off, and similar requests to lock or unlock the doors. Other POST requests send URLs to the in-car browser. With all the options, a whole range of applications becomes possible.
To demonstrate the way you can call the Auto API with Postman we have prepared a quick video:
Conclusion
The platform is designed to handle complexities arising when working with connected cars from a variety of manufacturers, and provides a consistent, unified way to access car data cross-OEM. Using Postman, it is easier than ever to see how the Auto API works in real-time.
