How to Use Postman to Streamline API Development in Fortellis

Brandon Boyd

Fortellis

Teams can use Postman to test APIs and design workflows for interacting with APIs before they create their backend or front end systems. With Postman, teams can capitalize on agile workflows to increase their productivity and decrease their time to deliver.

Postman Collections are an organizational feature you can use to group API requests and save them in an arrangement that serves a specific use case. You can create collections for personal use or to share with teams and to the general public.
To get up and running with testing API development, we’ll be walking through the steps to create a Postman collection with three requests to an API on the Fortellis Automotive Commerce Exchange, an API platform for the automotive industry.

Use case for our Postman collection

As the internet manager for a car dealership group, I want to find all Ford Explorers across my 10 rooftops including VIN, image URLs and lot location so I can promote these cars online because there is an upcoming manufacturer incentive.

Requirements

You’ll need to create a Fortellis account, so you can access test APIs

Once your Fortellis account is approved, you can then create a test app and select the Merchandisable Vehicles V1 API under the “Testing Only” tab.

Before getting started, you’ll also need to create a postman account and download the Postman desktop app.

Let’s get started

Select “New” to create a new collection.

Enter “name” and “description.”

These fields will become very important down the road as they are the two fields which populate the documentation for your API collection. One nice feature here is that the description field supports Github-flavored Markdown format, which you can use to create code blocks, lists and tables and can make your documentation easier to understand for other developers.

We’ll name our Postman collection “Explorer Incentive” to match our use case. We’ll be connecting to the Merchandisable Vehicles API for testing purposes. This API connects to the CDK Global Vehicle Cloud back-end service. If the dealer is using a CDK website, the inventory is stored in this cloud service and can be accessed through the API. Inventory from other website providers may be supported through an import process to the vehicle cloud.

The Merchandisable Vehicles API include all vehicles available for sale or lease from the dealership, and it goes far beyond basic specifications, features and technical details to include financial information like pricing and incentives, and marketing media like thumbnails, still photos, and videos of the vehicle in action. The API allows users to search for vehicles based on location, vehicle specifications, price, and mileage. When a vehicle is identified, it can retrieve the full range of vehicle information.
*Note This API is in beta mode and available for testing only.

How authorization works in Fortellis

Fortellis Authorization Tokens are created using the Fortellis identity endpoint by creating a POST request and passing your Fortellis API key and secret. Your API key and secret are created for you when creating a test “app” in the Fortellis developer network.

Remember, Fortellis authorization tokens are valid for an hour (3600 seconds), and when they expire, you will need to request another token before making an API request through the platform. One helpful way to organize your collection when using Fortellis APIs is to include an authorization request in each of your collections, so you can request a new token to pass to your subsequent requests.

Now that we have a collection created, let’s add some requests and explore some cool features to see what we can do with it.

Requesting a bearer token from the Fortellis identity endpoint

To request a bearer token, we will create a POST request in Postman.

Select “New” Request in the Postman app

Name your request “Fortellis Identity Request,” add a description and save to the newly-created “Sample Fortellis Collection.”

Next, enter the following information into Postman:

Fortellis Identity Token (Request Details)

Request Type

POST

URL

https://identity.fortellis.io/oauth2/aus1p1ixy7YL8cMq02p7/v1/token

Headers (Header Parameters)

KEY	VALUE
Accept	Application/json
Cache-Control	No-cache
Content-Type	Application/x-www-form-urlencoded

Params (Body Parameters)

KEY	VALUE
grant_type	client_credentials
scope	anonymous

Authorization

Type: Basic Auth
Username {{key}}
Password {{secret}}

Using Postman variables in an authorization request

Since we plan on sharing our Postman collection so others can collaborate, we need to find a way to keep our API Key (Username), API Secret (Password) and Bearer Token private for security purposes. So let’s take a look at Postman Variables.

Postman variables are denoted by double curly braces and can be used throughout your API requests. For the authorization tab of our POST request to the identity endpoint, we’ll need to input the following variables in the Username and Password fields.

Username {{key}}
Password {{secret}}

Assigning Postman environment variables

Now that our variables have been added to our POST request to the Fortellis Identity endpoint, we need to set the values for the variables in our Postman Environment. By assigning our variables inside an environment, it keeps our personal credentials safe when sharing this Postman Collection with others.

1. Select the gear icon in the Postman app, which will pull up the “Manage Environments” menu
2. Select “Add”
3. Name your environment
4. Create three variables

VARIABLE	INITIAL VALUE	CURRENT VALUE
key		***your Fortellis API Key goes here***
secret		***your Fortellis API Secret goes here***
token		***Once you make your post request, copy and paste your token here***

If you’ve created a test app inside of your Fortellis Developer Account, you can copy your API Key and Secret and paste the values into the respective Postman environment variables above.

Note: we will populate the token variable once we run our authentication request

Sharing of credentials and secrets

Fortellis advises not to share credentials or secrets when sharing Postman Collections. All requests to Fortellis using your credentials will be taken on your behalf in terms of access control, auditing, and billing.

Run your Fortellis authorization request

Ensure your request type, URL, parameters, headers and authorization types and variables are set up correctly. Now it’s time to send your request and get your token.

Click the blue “send” button and you should see a 200 OK response, which will include your access token. Copy and paste this alphanumeric token into your environment variable into the “current value” column.

Query the MVS API in Fortellis to find Ford Explorers and drill down to see more detail

Create two new requests in your collection with the following details. Click the “send” button to see the results. Once you submit the first request, you’ll have a list of Merchandisable Vehicle IDs (unique identifiers) of Ford Explorers across the rooftops in our group. In the second request (query merchandisable vehicles by ID), we will pass a specific ID found in our first query to get vehicle details.

Query Merchandisable Vehicles (Request Details)

Request Type

https://api.fortellis.io/sales/inventory/v1/merchandisable-vehicles

Headers (Header Parameters)

GET

URL

KEY	VALUE
Subscription-Id	test

Params (Request Parameters)

KEY	VALUE
merchandisableVehicleId	fe09as90-a213-543d-2165-4da287631b19

Authorization

Type: Bearer Token/
Token {{token}}

Let’s review our Postman Collection

Our use case was to help an internet manager find Ford Explorers for an upcoming promotion and provide image URLs, VIN and lot location. Here’s a snippet of our response from our third API call (Query Merchandisable Vehicle by Id), which shows the image URL, VIN and lot location.

Hopefully this helps you quickly test Fortellis APIs and provide a view into some Postman features that can streamline development. If you have any questions or comments, please chime in below.

Use the Fortellis collection we just created

Run in Postman

*Note: remember to start using this collection, you’ll need to click the “gear” icon in Postman and enter your Fortellis API key, API secret as “Environment Variables”. After you run your post request to the Fortellis identity endpoint, you’ll copy and paste your token into the Postman Environment variables as well to run the second and third request.

Valuable resources for further reading and exploration

How to automatically set a bearer token for your postman requests
Intro to postman collections
Manage environments in postman
Postman Tutorial | Postman Crash Course for Beginners | Learn API Testing using Postman (YouTube)
Fortellis Authentication and Authorization