In Part 2 of this post, I reviewed the basics of setting up a web service access key, finding your first API, and then executing the API in your browser.
But the output we had wasn’t all that user friendly. Further, we asked for EVERY account in the system. In this case, there wasn’t a huge amount of data so it wasn’t a problem. But it’s not something you’d want to do with G/L Entries or other larger tables.
Fortunately, you can do a lot more with these ODATA Web Services than just select everything. Theoretically, you could create ever more complex strings and test them in your browser. But that’s not really efficient.
Which brings us to a tool that’s called Postman.
Postman
Postman is a tool for testing and building APIs. We’re only interested in its testing capabilities.
While there are different paid levels of the product, so far it seems that the free version is enough for testing APIs. To sign up, go to https://www.postman.com/.
You can do everything you need in the web version. But even with a free subscription, you can download a PC-based software.
(There may also be a Mac version, but I’m not sure. I tried switching to Mac once a few years ago. It wasn’t a happy experience, so you’re on your own.)
There are many videos on how to get started with Postman. I liked Steve Griffith’s https://www.youtube.com/watch?v=t5n07Ybz7yI.
Since I’m using these blog articles to prepare for various presentations I’ll be giving on the topic, I’m going to walk through the basic of Postman here.
(Unfortunately, I can’t tell those attending my presentation to go watch someone else’s video for 10 minutes. Which is too bad because it would reduce my preparation time.)
Here’s what the screen looks like when you download the software and open it on your computer:
Postman Workspace
The first thing to do is choose a workspace.
Workspace is associated with a group of people for source control purposes. Here’s the full explanation from Postman https://blog.postman.com/2018/04/07/workspaces-the-biggest-thing-to-hit-postman-this-month/.
As you’re just getting started, we’re not that interested in source control. So, the first thing you need to do is to create a new workspace.
Click the My Workspace dropdown and select Create New:
Then enter a new name. I’m going to call it Data without a Database – Part 3.
Next, click Personal.
When you choose Personal, the Invite people to join this workspace disappears.
You can then click on Create Workspace:
Postman Collections
Once you’ve created a workspace, the next page appears. You haven’t done anything yet, so it doesn’t have much on it (as we would expect).
The first thing you need to do is create a collection. Collections lets you group together related requests, making them easier to access and run.
Look to the left where it says You don’t have any collections along with an explanation.
Click on Create a collection:
And this page appears:
I’m going to name my collection BC (for business central), redthree.com (the domain used with my business central subscription) and CRONUS US.
I’m doing this because I like to have each collection work on a basic instance and web service access key. This will make it easier to test different flavors of Business Central APIs.
Before you click Create, you want to move to the Authorization tab:
Which brings up this screen:
Under TYPE, I’m going to choose Basic Auth:
Then you enter your username as described in Part 2 of this series (in this example, I’m using ADAM) and the Web service access key (which you stored securely in accordance with my instructions, also in Part 2):
BTW, you’ll also see a tab for Variables. I will get to this latter.
But for now, click Create and you’ll have your collection.
The screen now looks like this:
You’ll see the message that the collection is empty.
To enter your first API request, you need to click on the three dots to the lower right of the collection name.
Clicking that brings up a context menu. Choose Add Request:
You can then enter your request name, ODATA – Accounts, and click Save to…:
This takes you back to the collection screen.
Next, you need to expand the collection:
After which you’ll see the request you created:
You can double click on the name to open the request in a new tab. Now, you can start working on your actual request, which is the web service API we used in Part 2 of this series.
Here’s the ODATA Web Service API for the Chart of Accounts:
You can simply put this into the GET box where it says Enter request URL:
I’m almost ready to click Send, but I want to demonstrate one more thing that will illustrate the importance of collections.
Click the Authorization tab under the GET request:
You’ll see that TYPE is set to Inherit auth from parent. Which means you don’t have to do anything. And as you create more requests in this collection, you can always share the same authentication:
Let’s click Send:
After a few seconds, your nicely formatted JSON values appear with field names and values you should recognize from your CRONUS US database:
If you move your mouse to the column to the right of the numbers, you’ll see various arrows:
These arrows allow you to collapse the output data so you can look at the next records.
For example, if I click the arrow next to number 4, I see the following:
Entry number 1 collapses and entry number 2 remains.
One last thing before I finish this post. Instead of clicking Send, you can use the dropdown to select Send and Download:
After a few seconds, you’ll be asked to save the file:
You can open the file in Visual Studio code. When it first shows up, you’ll see there are no line breaks:
But if you right-click on the document, you can select Format Document from the context menu:
After you do that, you can see the data nicely formatted:
One more thing before we finish. Go back to Postman to make sure you save what you’ve done.
Simply click Save to the right side of the GET request:
Now that you’ve run your first request, in my next blog post I’ll get into other things that you can do in Postman.