Using Postman

Postman is a free API development environment you can download here. It's another useful tool for testing the Prime API, in addition to the Prime API Client.

This page contains resources to help you set up your environment correctly, plus examples of successful GET and PUT calls to the Prime API.

Requirements

• Download the Postman app
• Configure Postman for mutual TLS
• Set up your Postman environments
• Generate and view the API Endpoints docs for reference
• Make sure you have the server running via make run_prime_docker. For more setup help, check out Getting Started.

Import YAML

You can simplify your setup process by importing the yaml files into Postman and creating a collection for each set of endpoints: prime.yaml for the Prime API, and support.yaml for the support endpoints.

• In the Postman app, click the Import button in the top left corner.
• Under the Import File tab, click Choose Files.
• Navigate to the mymove/swagger directory, select prime.yaml, and click Open.
• Click Next to create a collection of the Prime API endpoints.
• Repeat this process, selecting support.yaml instead.

Select Postman Environment

Make sure you've selected the correct environment for the set of endpoints you're using.

• When using the Prime API, select the Prime Local Environment from the dropdown menu in the top right corner.
• When using the Support API, select the Support Environment from the dropdown menu in the top right corner.

Learn more about the endpoints in the API Endpoints section.

Example: GET

For this example, let's make a GET request to the /move-task-orders endpoint, which will return all move task orders.

• Looking at the generated API docs, we can see there are no required params or headers.
• In the left sidebar, click on the move.mil API collection folder > move-task-orders folder.
• Click GET Gets all move task orders to open the request window.

• Since there are no required params or headers, click the Send button.

• Successful output will look similar to below:

Example: PUT

For this example, let's make a PUT request to the /mto-shipments endpoint to update an existing MTO shipment.

• Looking at the generated API docs for PUT /mto-shipments, we can see the following data is required to make our request:

  • Path Params:
    • mtoShipmentID
  • Header Params:
    • If-Match
      • Note: This is listed in the JSON response as eTag

• Fetch this existing data by using the GET /move-task-order endpoint.

  • In the JSON response, find the shipment object you'd like to update.
  • Copy the required data to use in your PUT request.

• In Postman, select your Prime Local Environment from the dropdown menu in the top right corner.
• In the left sidebar, click on the move.mil API collection folder.
• Click PUT Updates MTO Shipment by ID to open the request window.

• Select the Params tab, and paste in the mtoShipmentID value.

• Select the Headers tab, and paste the eTag as the value for If-Match.

• Select the Body tab, and paste in an object containing the required params and the attributes you want to update. For example:

{
    "scheduledPickupDate": "YYYY-MM-DD",
    "actualPickupDate": "YYYY-MM-DD",   
    "firstAvailableDeliveryDate": "YYYY-MM-DD"
}

• Click the Send button.
• Successful output will look similar to the following:

---

Return to top