Prime API Client

The Prime API Client, or prime-api-client, is a command-line tool for making calls to the Prime API. This section details how to use the client to make API calls locally.

Please note that you may generate a starter API client in many mainstream languages. To do so, visit the Swagger editor website, paste the contents of transcom/mymove/swagger/prime.yaml in the editor, and click on Generate Client.

Requirements

You've successfully run the Prime Docker via make run_prime_docker.

Setup

Compile prime-api-client binary

rm -f bin/prime-api-client
make bin/prime-api-client

To test, run prime-api-client in your shell. You'll see the available commands and optional flags:

Prime API client

Usage:
  prime-api-client [command]

Available Commands:
  completion                             Generates bash completion scripts
  create-mto-service-item                Create mto service item
  create-mto-shipment                    Create MTO shipment
  create-payment-request                 Create payment request
  create-upload                          Create payment request upload
  fetch-mto-updates                      Fetch all MTOs available to prime
  help                                   Help about any command
  support-create-move-task-order         Create a MoveTaskOrder
  support-get-move-task-order            Get an individual mto
  support-update-move-task-order-status  Make mto available to prime
  support-update-mto-service-item-status Update service item status
  support-update-mto-shipment-status     Update MTO shipment status for prime
  support-update-payment-request-status  Update payment request status for prime
  update-mto-post-counseling-information update post counseling info
  update-mto-shipment                    Update MTO shipment

Flags:
      --cac                   Use a CAC for authentication
      --certlabel string      Smart card: label of the public cert (default "Certificate for PIV Authentication")
      --certpath string       Path to the public cert (default "./config/tls/devlocal-mtls.cer")
  -v, --debug-logging         log messages at the debug level.
  -h, --help                  help for prime-api-client
      --hostname string       The hostname to connect to (default "primelocal")
      --insecure              Skip TLS verification and validation
      --keylabel string       Smart card: label of the private key (default "PIV AUTH key")
      --keypath string        Path to the private key (default "./config/tls/devlocal-mtls.key")
      --pkcs11module string   Smart card: Path to the PKCS11 module to use (default "/usr/local/lib/pkcs11/opensc-pkcs11.so")
      --port int              The port to connect to (default 9443)
      --tokenlabel string     Smart card: name of the token to use

Use "prime-api-client [command] --help" for more information about a command.

jq Library

The tool uses the jq library, which was installed as a dependency for the Prime Docker, to process JSON on the command line. In the following examples, you'll see | jq added on to the end of all commands.

Commands

Commands	API Endpoint	Description
`create-mto-service-item`	`POST /mto-service-items`	`Create mto service item`
`create-mto-shipment`	`POST /mto-shipments`	`Create MTO shipment`
`create-payment-request`	`POST /payment-requests`	`Create payment request`
`create-upload`	`POST /payment-requests/{paymentRequestID}/uploads`	`Create payment request upload`
`update-mto-shipment`	`PUT /mto-shipments/{mtoShipmentID}`	`Update MTO shipment`
`update-post-counseling-info`	`PATCH /move-task-orders/{moveTaskOrderID}/post-counseling-info`	`update post counseling info`
`fetch-mto-updates`	`GET /move-task-orders`	`Fetch all MTOs available to prime`
`support-create-move-task-order`	`POST /move-task-orders`	`Create a MoveTaskOrder`
`support-get-move-task-order`	`GET /move-task-orders/{moveTaskOrderID}`	`Get an individual mto`
`support-update-move-task-order-status`	`PATCH /move-task-orders/{moveTaskOrderID}/status`	`Make mto available to prime`
`support-update-mto-shipment-status`	`PATCH /mto-shipments/{mtoShipmentID}/status`	`Update MTO shipment status for prime`
`support-update-mto-service-item-status`	`PATCH /service-items/{mtoServiceItemID}/status`	`Update service item status`
`support-update-payment-request-status`	`PATCH /payment-requests/{paymentRequestID}/status`	`Update payment request status for prime`

For additional details on the endpoints, view the API Endpoints documentation.

Support Commands

The commands in the above list that start with support- comprise a suite of endpoints that will enable testing of the workflow.

They won't exist on production servers and therefore, shouldn't be relied on for any interactions in production.

They do exist in the local dev environment.

Usage

The Prime API client works by sending an http request to a running server. To use the client, you must run the server locally before attempting to send a request to the API endpoint.

Once the local development server is running, you may use the client in an insecure mode. prime-api-client --insecure

This will default to contacting the server at primelocal:9443

Getting Help

You can get help for a specific command in the client by using --help after the command name. This is just an example; do use the client to get an up-to-date version of this command.

prime-api-client --insecure update-mto-shipment --help

  This command updates an MTO shipment.
  It requires the caller to pass in a file using the --filename arg.
  The file should contain path parameters, headers and a body for the payload.

  Endpoint path: mto-shipments/{mtoShipmentID}
  The file should contain json as follows:
    {
      "mtoShipmentID": <uuid string>,
      "ifMatch": <eTag>,
      "body": <MTOShipment>
    }
  Please see API documentation for full details on the endpoint definition.

Usage:
  prime-api-client update-mto-shipment [flags]

Flags:
      --filename string   Name of the file being passed in
  -h, --help              help for update-mto-shipment

Simple Command Example

A simple command like fetch-mtos requires no parameters, headers or body in the http request.

Command: `fetch-mtos`

Fetches all move task orders
- GET /move-task-orders

Run

In your shell, run:

 prime-api-client --insecure fetch-mtos | jq

Sample output:

[
  {
    "createdAt": "2020-01-22",
    "id": "5d4b25bb-eb04-4c03-9a81-ee0398cb7791",
    "isAvailableToPrime": true,
    "isCanceled": false,
    "moveOrderID": "6fca843a-a87e-4752-b454-0fac67aa4981",
    "mto_service_items": [{ ... }],
    "mto_shipments": [{ ... }],
    "payment_requests": [],
    "reference_id": "1234-4321",
    "updatedAt": "2020-01-22"
  },
  {...},
]

Advanced Command Example

A more complex command might require headers, path parameters or a body, or all three.

We pass these values in a json file at the command-line. The way you'll structure the json is different than Postman or other tools.

You place the header and path parameters at the top level of the json, and the body is a nested object.

{
  "headerParam1": "headerValue1",
  "headerParam2": "headerValue2",
  "pathParam1": "pathValue1",
  "body": <bodyObject>
}

One example of a command that uses path parameters, headers, and eTag is the update-mto-shipment command. It requires the following:

A path parameter mtoShipmentID
A header parameter If-Match
A body with the updated MTO Shipment

ETags

Before updating an object, you need to figure out the eTag of the object you'll be updating.

It represents the state of the object when you last received it. To avoid conflict, your eTag must match what is currently in the database for this object.

You should have received it the last time you updated the object but can also find it for most objects using the fetch-mtos sub-command.

Command: `update-mto-shipment`

Updates an existing mto shipment
- PUT /mto-shipments/{mtoShipmentID}

You can see documentation of the endpoint in the Redoc to get the details.

Run

In your shell, run:

prime-api-client --insecure update-mto-shipment --filename {PATH TO FILE} | jq

Sample Output:

{
  "actualPickupDate": "2020-03-25",
  "agents": [
    {
      "agentType": "RELEASING_AGENT",
      "createdAt": "0001-01-01",
      "email": "[email protected]",
      "firstName": "Test",
      "id": "b870fe0c-f2a1-4372-9d44-eaaf54a1b45d",
      "lastName": "Agent",
      "mtoShipmentID": "df2725cf-ee88-4fe5-90e7-a693b551dd3a",
      "updatedAt": "0001-01-01"
    },
    {...}
  ],
  "createdAt": "2020-03-25T15:42:28.992Z",
  "customerRemarks": "please treat gently",
  "destinationAddress": {...},
  "eTag": "MjAyMC0wMy0yNVQxNTo0MjoyOC45OTI1ODFa",
  "id": "df2725cf-ee88-4fe5-90e7-a693b551dd3a",
  "moveTaskOrderID": "5d4b25bb-eb04-4c03-9a81-ee0398cb7791",
  ...
}

Polymorphic API Example

Some APIs have polymorphic types, which means you'll have to supply the modelType as well as the contents.

Create MTO Service Item is an example of a polymorphic typed API.

Please see the Redoc for full details.

Command: `create-mto-service-item`

Creates a new mto service item for a shipment
- POST /mto-service-items

Run

In your shell, run:

  prime-api-client --insecure create-mto-service-item --filename {PATH TO FILE} | jq

Sample Output:

{
  "pickupPostalCode": "90802",
  "reServiceCode": "DOFSIT",
  "reason": "sometimes stuff happens",
  "eTag": "MjAyMC0wMy0yNVQxNjowMTowMS41ODg0MTha",
  "id": "10873d77-b617-40a3-a66d-3b8f4389ba5e",
  "modelType": "MTOServiceItemDOFSIT",
  "moveTaskOrderID": "5d4b25bb-eb04-4c03-9a81-ee0398cb7791",
  "reServiceID": "998beda7-e390-4a83-b15e-578a24326937"
}

Return to top

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Prime API Client

Requirements

Setup

jq Library

Commands

Support Commands

Usage

Getting Help

Simple Command Example

Command: `fetch-mtos`

Run

Advanced Command Example

ETags

Command: `update-mto-shipment`

Run

Polymorphic API Example

Command: `create-mto-service-item`

Run

Clone this wiki locally

Prime API Client

Requirements

Setup

jq Library

Commands

Support Commands

Usage

Getting Help

Simple Command Example

Command: fetch-mtos

Run

Advanced Command Example

ETags

Command: update-mto-shipment

Run

Polymorphic API Example

Command: create-mto-service-item

Run

Clone this wiki locally

Command: `fetch-mtos`

Command: `update-mto-shipment`

Command: `create-mto-service-item`