DEV Community

Cover image for Using the Postman workspace 📮
Joanne for

Posted on

Using the Postman workspace 📮

An easy way to test out the API is by using Postman, a platform that allows you to make API calls right within your browser or desktop app. This way, before you get to building your brokerage product, you’ll know exactly what’s possible. We’ve set up a Postman workspace that can be used to familiarise yourself with the endpoints that we offer in our Market Data and Trading APIs. You’ll see just how simple it is to, for example, place a trade with (hint: it’s just one API call).

Why Postman? 📯

Postman is an easy-to-use application that allows you to test out an API without having to manually set up a testing environment. It’s as simple as filling in a request URL, providing the proper authorisation and inputting the relevant query/request body parameters. Luckily for you, we’ve already set up a Postman workspace with all requests included, all you need to do is fork it, fill in your API key and start sending requests.

Using Postman 👨

The Postman workspace can be found here. For personal use, you need to import the workspace into your own Postman account. Let’s see how that’s done!

Forking the workspace 🍴

We’re assuming you already have a Postman account, but if you don’t, you can easily set one up, here. Because the workspace is public, you need to fork it into your own workspace to be able to send requests.

_Forking the workspace_

To fork our workspace, click the ‘…’ next to the collection of your choice and select ‘Create a fork’.

You’ll be prompted to give the fork a name and select a workspace to copy it into. You can choose to create a separate workspace, or simply copy it into the default ‘My Workspace’.

To make requests, you’ll need to set up several environment variables — we’ve also set up a template for this (which you can also fork in the same way).

Image description

The environment templates can be found under the conveniently named ‘Environments’ tab on the left hand side.

Configuring the environment 🌳

To set-up your environment, you’ll want to fill in your API key (this can be found on your dashboard). Because your workspace is only accessible to you, it doesn’t matter whether you fill it in under ‘Initial Value’ or ‘Current Value’, but as a best practice, you should always fill in sensitive information under ‘Current Value’. This prevents the information from being synced with the Postman workspace (especially important if you’re working in a (semi-)public workspace).

Image description

You’ll know you’re in your forked workspace due to the Ψ next to the environment name — notice I’ve called my fork ‘lemon_tutorial’.

If you already know which Space you’d like to operate in, you can also fill in the ID here. But, if you still need to create a Space or don’t know its ID, we’ll show you how you can use the Trading API workspace to access this information.

Make sure you save any changes (upper right-hand corner) and set the environment active, you can do this by hovering over its name and clicking the check-mark, which should become grey upon success.

If you’ve properly set up your API key and environment, the environment should appear in the upper right-hand corner (as can be seen in the screenshot below). Additionally, if you navigate to the authorisation tab for either Collection, hovering over {{API-KEY}} should display the key you’ve filled in.

Image description

If you can’t see your API key upon hovering, ensure that your environment has been saved and set active (you might need to manually select it in the upper right-hand corner if you have more than one environment).

Making your first request ❓

Let’s begin by getting a list of our Spaces. Navigate to the ‘Space’ folder in the Trading API collection. Here, you have the option to retrieve a list of Spaces or a single Space, but also to create, delete and alter a Space (these are all the functionalities that our /spaces/ endpoint offers).

Image description

If you haven’t filled in a Space ID yet, you can copy one from the desired Space after placing this request and paste it into your environment (remember to save!). You’ll need to place other requests. You can also create a new Space using the POST request that can be found under the same Space header.

The API response can be found in the console below after clicking the blue ‘Send’ button. In the screenshot, my Space ‘Postman Space’ created on 24 November 2021 can be seen (scrolling shows my other Spaces).

You can also specify query parameters in your request. In this case, you can choose to filter by Paper Money and Real Money Spaces, all you need to do is toggle the ‘type’ key, fill in a value and run the request again. More on that in the next section. 👇

Other important considerations 🤔

To get the most of the workspace, we recommend you read the following tips:

Some endpoints, for example the /ohlc/ endpoint in our Historical Market Data API, have mandatory query parameters. For all query parameters that are required, we’ve configured the workspace to automatically toggle that parameter (indicated by the checked box). But, whether it is optional or required can also be found in the key-value description. In addition, some requests also require path variables as input — these are listed below any query parameters (they can also be recognised in the request URL by a ‘:’). If specified, these are always required.

Image description

Note that ‘isin’ is the only required query parameter for this endpoint, we also need to specify the path variable ‘x1’ in order to send this request.

Other endpoints require a request body, you’ll recognise this by the green dots next to the headers underneath the request URL. For example, for the /orders/ endpoint in our Trading API, you’ll notice the green dot next to ‘Body’, this means that we need to fill in information here. Notice that there’s a lot of required variables here! I’ve filled in some example values below.

Image description

In the above screenshot, you’ll see I placed a buy order for 2 shares of Tesla.

All other requests follow a similar format — some require you to fill in both ‘Params’ and ‘Body’ variables. Keep an eye out for those green dots!

You’re ready to explore on your own! How about you try placing and activating a trade? And then having a look at your portfolio? Have a look at our documentation to see what’s possible.

Over to you! 🤝

We want to know how we can make this collection better! If there’s any improvements that come to mind, do not hesitate to reach out to us through Twitter, Instagram or Slack. And remember, if you haven’t signed up to yet, do that now to kickstart your automated trading journey.

Joanne from🍋

Discussion (0)