Introduction
Within the API Team at Ferguson, Postman has become an integral part of our API development pipeline. There is rarely a day that goes by where I don’t spend an hour or two utilizing the tool. So what exactly is Postman? It’s a software development and collaboration tool focused on API documentation, testing, and monitoring. There is a free version that you can download and start to use right now. The following guide will walk you through creating your first collection and request to hit the Ferguson Hello World endpoint.
Quickstart Guide
Pre-Requisites:
- Download and Install Postman
- Sign up for a free account
This guide will walk you through the steps needed to create your first Postman collection and request that will call our Hello World API. You can find the swagger for this API within our API Catalog.
Collection Creation
- When logging in for the first time, you will see that you don’t have any current collections. Click + New Collection or + Create a collection on the left side of the application window.
- You will see the following popup box to be filled out. Let’s call this collection Ferguson API and add an appropriate description then click Create in the bottom right corner.
You will now see your newly created collection on the left hand side.
Request Creation
We want to call the version 0 /hello endpoint of our Hello World API.
- Time to create our first request! Click on Add requests.
- Fill out the request information with appropriate name and description. Verify that the request is being saved to your newly created collection.
Click Save to Ferguson API
- Select your newly created request in your Ferguson API collection. The request will be blank besides the name so let’s fill in the appropriate information based on our Swagger.
The url and endpoint we want to hit is: https://uatapi2.ferguson.com/v0/hello
Update your request URL to match.
We can verify with the Swagger that this is a GET call that has no params or payloads.
For more complicated requests you will see multiple tabs within the request where you can add on the appropriate authorization, query params, and payloads.
- From here, we can Save and then Send the request!
- You should see the below 200 OK response:
This matches the swagger response, so we have successfully made our first Postman request.
Next Steps:
So what should you do now?
If you already have a Developer App for Ferguson APIs - verify that you have added our Hello World API and try making a call to the version 1 endpoint. If you don’t have a Developer App yet, please fill out our Contact Us form to get one created.
Hint: you will need to grab an OAuthv2 access token and add it to your authorization tab. If you have questions around how to do that, visit our earlier blog post OAuth 2 Client Credentials Overview.