Using Postman to work with the Genesis API

Owned by Scott Huiskens (Unlicensed), created
Last updated: Mar 31, 2022 by Patrick Murphy
3 min read

Postman is a useful tool that can help you test, and then experiment with, the Genesis API. You can use Postman with on-prem or ESHA Cloud hosted instances of the Genesis API and it’s a great way to become familiar with the different Genesis API endpoints and their capabilities.

What you’ll need:

  • Postman (which you can get from here)

  • If you're using an on-premises installation of the Genesis API, you'll need the URL where the endpoints were installed. Contact your Network Administrator or whomever installed the API for that information.

The URL will typically look like:
https://mylocalnetwork.com:<portnumber>
where <portnumber> is something like 8080 (or another open port on your network)

  • If you're using the Genesis API hosted on ESHA Cloud, you will need the onboarding email that was sent when the API was set up for you. That email will contain the specific URL you will connect to as well as the Basic Authentication credentials you will need. If you did not receive that email, contact ESHA Support and request it be resent.

Create a Workspace and a Collection

  1. Install and launch Postman

  2. Click “Workspaces” in the upper left of the window to open the Workspaces menu

  3. Click “+New Workspace”

  4. Name the workspace “Genesis API Testing”

  5. Click the “New” button, select “Collection” from the dialog that appears, and name your collection “Genesis API 4.x” 

If your local network needs authorization credentials to connect to the provided URL, or if you are using the Genesis API hosted in ESHA Cloud, follow the steps in the “Configure Authorization” section. If not, skip ahead to the “Send a Request” section.

Configure Authorization

  1. In the left pane, where the “Genesis API 4.x” Collection is visible, hover over its name and click the ellipsis that appears

  2. Click “Edit”

  3. In the main pane, click the “Variables” tab

  4. Where it says “Add a new variable” enter “GenesisApiId” (without the quotes)

  5. Under “INITIAL VALUE” enter your ID from the onboarding email or from your Network Administrator. Be certain the “CURRENT VALUE” also includes your ID.

  6. Add another variable called “GenesisApiPw” (without the quotes)

  7. Leave “INITIAL VALUE” blank and enter your password in the “CURRENT VALUE” field

  8. Select the “Authorization” tab

  9. If you are using the Genesis API hosted in ESHA Cloud, change the “Type” to “Basic Auth”, or whatever authorization is required for your network

  10. For “Basic Auth”, in the “Username” field, type {{GenesisApiId}}

  11. Click the “Show Password” checkbox

  12. In the “Password” field, type {{GenesisApiPw}}

  13. Click the “Save” button in the upper section of the main pane

Create and Send a Request

For the purposes of this guide, we will be using https://mylocalnetwork.com:8080 as the URL. Replace this with your specific URL from the start of this guide.

  1. In the left display pane, expand “Genesis API 4.x” and click “Add a request”

  2. Enter “ListUnits” for the name of the request

  3. Change “GET” to “POST”

  4. Where is says “Enter the request URL” enter the following:

    https://mylocalnetwork.com:8080/rest/FoodQueryService.svc/ListUnits

  5. Click on the “Body” tab below the URL

  6. Click on the “raw” radio button

  7. Ensure that the drop down to the right of “GraphQL” shows “Text” and if it does not, change it to “Text”

  8. In the text box where you see “1” displayed, enter the following request:

    request={}

  9. Click the “Save” button to save the request in your Workspace

  10. Click the blue “Send” button to send the request to the endpoint

  11. You should get a list of units in the bottom pane with a “Status” of “OK 200”

This same pattern can be used for any of the endpoints you wish to test. For some endpoints (e.g. ListUnits, ListNutrients, etc.) an empty request (request={}) is valid. For most it is not. See the documentation for all endpoints for sample requests that can be copy/pasted into Postman and used for testing.

You can find more information on Postman and its capabilities here.

Related articles