Step 2 - Getting Started with Postman
9 min
overview postman is an api client used to build and test restful apis you can use postman to send http requests (get, post, put, delete) to the zen master api the response from the api will be a json object in this document, we'll cover these topics install postman download the api definition import the api definition define environment variables link to postman vault (optional) send a get request for sources as an api user, you will have admin access in zen master, allowing you to view objects and update all settings available to administrators install postman to get to the postman homepage, open a web browser and navigate to https //www postman com/ there are a few ways to use postman use the web version download the postman app and install it on your machine use the vs code extension create a postman account or sign in download the api definition download a copy of the zen master api definition either yaml or json format works in postman log in to the zixi customer portal in the left navigation, select documentation select the by type tab, and then select zen master api to download the json file open the zen master api html reference at the top of the api reference, click the download button a json file will be downloaded to your computer to download the yaml file in the zixi customer portal, locate the zen master api yaml file click the download button a zipped yaml file will be downloaded to your computer import the api definition in postman, the api definition (yaml or json) will be imported as a collection in a web browser, navigate to https //www postman com/ https //www postman com/ sign in or create an account in the left sidebar, click import select your copy of either the yaml or the json api definition file select postman collection this will import the api definition as a postman collection selecting openapi 3 0 specification with a postman collection will create a postman collection and a specification on spec hub , which is used for designing an api click import define environment variables next, you will define postman variables to provide access to the zen master api there are several ways to do this we'll focus on environment variables setting up postman environments makes it easy to switch between staging and production, which have different urls and api key values return to the postman ui in the left navigation, select environments and click + to create a new environment rename the environment add the baseurl variable for the baseurl variable, enter the zen master api base url https //api zen zixi com/v2 https //api zen zixi com/v2 leave the initial value field blank paste the baseurl value into the current value field never put sensitive data in the initial value if you are in a shared or public workspace, anyone with access to that environment will see your data the current value is stored locally on your machine and is not synced to the postman cloud by default add the apikey variable if you don’t already have a zen master api authentication key, see the getting started with authentication document leave the initial value field blank paste the zen master api key value (you created in the zixi zen master dashboard) into the current value field set the variable type to secret the value is masked in the postman ui click save in the left navigation, click collections to return to your zen master api collection in the top right, expand the no environment drop down menu and select the environment that you just created your environment variables are now available for each method request in your collection link to postman vault (optional) for maximum security of your api key values, it is best practice to combine environment variables with postman vault postman vault is designed to store your sensitive data locally and securely it keeps your secrets off the cloud and local to your machine let's add our api key to the postman vault in postman, in the bottom right corner, select vault copy your vault key and save it in a password manager you will need it to log in to your vault after logging out losing your postman vault key will result in the loss of all of your secrets click open vault store your api key in the postman vault (ex, myapikey ) return to your environment variables and replace the current value with {{vault\ myapikey}} set the type to secret for ui masking return to your collection and select your environment you are ready to send requests send a get request for sources send a request to the zen master api to test your connection in the left sidebar, select the zixi zen master api collection, and expand the sources folder select get list sources for the get url endpoint, remove all of the query parameters click send you should see response data with an array of sources for a complete list of request paths, see the zixi zen master api reference