Postman is an application that makes calling APIs intuitive from a GUI interface. We leveraged its usability to help you get started with the Swift APIs. If you are new to Postman, we invite you to read more about it on their official website.
Download the postman app from the download page.
On the Reference page, APIs with Postman Collections have a Run in Postman button.
Upon clicking this button, a popup appears which provides you with 3 options:
View Collection
This option opens a tab in your browser, directing you to the Swift Developer Portal Public Workspace. You can look at all available APIs. While viewing the Postman Collection in this Public Workspace, you will not be able to make API calls. The option for viewing is read-only.
Import a Copy
If you have Postman installed, you will be prompted to open Postman in order to import. You will have the opportunity to select which Workspace you would like to import the collection to. After that, you will have a copy of the collection that you can use to make API calls to the Sandbox. This imported copy is static; if any changes are made to the collection in the Public Workspace, you will have to re-import to see them.
Fork Collection
This option opens up a new tab in your browser. If you are logged in to your Postman Account, it will bring up a form to let you set the label, workspace, and notification settings for your fork. On clicking Fork Collection the fork is added to your specified workspace. With a fork, you will be able to make API calls to the sandbox, stay updated on the latest changes, and collaborate through Pull Requests. For more information on forks, please see the Postman documentation.
Now that you have a Postman Collection in your workspace, you must set your app credentials. If you do not have a set of app credentials, please see our Getting Started Guide.
There are two methods you could use to set your credentials for making calls to the API Sandbox.
Edit the collection variables
Each Postman Collection has its own set of variables. These variables can be applied to any call within the collection. If you have forked the collection with the intent to create a pull request, please do not update the collection to contain your app credentials or any other sensitive data.
At the top folder of the Postman Collection, select the Variables tab. In this tab, replace the indicated values with the consumer-key and consumer-secret from the app that you have created. Make sure to click the Save button on the top right after updating the values.
Create an Environment
In this method, you can have a set of variables that are applied to any API call in your workspace while the given Environment is enabled. In case you have multiple apps with different products, please be aware of which environment you have active.
To create a new Environment, click the button that says New. This brings up a popup with different options. Select the option to create a new Environment.
With your Environment created, you can provide a meaningful name for it. Then add the variables consumer-key and consumer-secret. Set your app credentials as the Initial Value as well as Current Value for these variables. Make sure to click the Save button to ensure your credentials are saved.
In order to set an Environment to be Active, hover over the name and click the checkmark.
A filled in checkmark indicates an active Environment.
Now that you have your credentials set, you can run the Postman Collection.
Individual APIs
To run APIs individually, you will first need to get an OAuth token using your app credentials. In order to get a better understanding of the OAuth schemes used by Swift APIs, please see Swift OAuth Token API page.
For this example, we are exploring an API that uses the JWT Bearer grant type for OAuth. There is an API call labeled as Generate Token in the collection. Open that request and click send. When a successful response is returned, your OAuth access token is automatically populated for the requests you send. This token will last for 30 minutes before expiring.
After getting your OAuth access token, you can select any other request in the collection to run. Each request in the Postman Collection is populated with sample data that is compatible with the API Sandbox.
Postman Collection Runner
In the top right of your collection, there is a button called “Run” which allows you to run the collection.
After clicking the button, the Postman Collection Runner allows you to configure the run. You can reorder the requests, set a number of iterations, and set a delay between requests. It is recommended to follow a similar order to the example below.
As the API calls are completed, they will show up in the run screen. This view shows what tests are run on the response and if they have passed. You can filter the results based on whether the test has passed.
In addition to the test results, you can click on the individual requests to view a variety of information about the data.
For further information on the Collection Runner, please see the Postman documentation.