Skip to content

Prime API Client

Jump to bottom
Abigail Young edited this page May 12, 2021 · 47 revisions

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-agent                       Create mto agent
  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-list-mtos                      Fetch all MTOs
  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
  support-get-mto-payment-request.       Get all payment requests for a given MTO
  support-create-webhook-notification    Create a Webhook Notification in the support api
  update-mto-agent                       Update an agent associated with an MTO shipment
  update-mto-post-counseling-information Update post counseling info
  update-mto-shipment                    Update MTO shipment
  update-mto-shipment-address            Update MTO shipment address

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

Our examples take advantage of the jq library, which was installed as a dependency for the Prime Docker, to process and format JSON on the command line. You'll see | jq added on to the end of all commands--this is an optional step to make the output more readable. If you experience issues with calling a command, dropping the | jq prefix may help you troubleshoot the problem.

Commands

Commands API Endpoint Description
create-mto-agent POST /mto-shipments/{mtoShipmentID}/agents Create MTO agent associated with MTO Shipment
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-agent PUT /mto-shipments/{mtoShipmentID}/agents/{agentID} Update MTO agent associated with MTO shipment
update-mto-shipment PATCH /mto-shipments/{mtoShipmentID} Update MTO shipment
update-mto-post-counseling-info PATCH /move-task-orders/{moveTaskOrderID}/post-counseling-info update post counseling info
update-mto-shipment-address PUT /mto-shipments/{mtoShipmentID}/addresses/{addressID} Update MTO shipment address
fetch-mto-updates GET /move-task-orders Fetch all MTOs available to prime
support-list-mtos GET /move-task-orders Fetch all MTOs
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
support-get-mto-payment-request GET /move-task-orders/{moveTaskOrderID}/payment-requests Gets all payment requests for a given move task order

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 against a local instance, 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

To use the client with our deployed environments, staging and production, you will need to have registered your CAC certificates and use those to connect to the server. The --insecure option will no longer be available to you in these environments. More instructions on how to interact with the Prime API in deployed environments coming soon #TODO

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-mto-updates requires no parameters, headers or body in the http request.

Command: fetch-mto-updates

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

Run

In your shell, run:

 prime-api-client --insecure fetch-mto-updates | 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-mto-updates sub-command. Example:

{
  "createdAt": "2020-04-30",
  "eTag": "MjAyMC0wNC0zMFQwMTowNDowOS44MzI5ODNa",
  "id": "da3f34cc-fb94-4e0b-1c90-ba3333cb7791",
  "isAvailableToPrime": true,
  ...
  "mtoShipments": [
    {
      "actualPickupDate": "0001-01-01",
      "agents": [...],
      "approvedDate": "0001-01-01",
      "createdAt": "2020-04-30T01:04:09.849Z",
      "customerRemarks": "please treat gently",
      "destinationAddress": {...},
      "eTag": "MjAyMC0wNC0zMFQwMTowNDowOS44NDkwOTha", <- ** you need this value for If-Match header
      "firstAvailableDeliveryDate": "0001-01-01",
      "id": "05892b31-1374-4fbf-b9d8-184aa1a4ee7a", <- ** you need this value for path parameter
      "moveTaskOrderID": "da3f34cc-fb94-4e0b-1c90-ba3333cb7791",
      "pickupAddress": {...},
      ...
    }
  ],
  ...
}

Command: update-mto-shipment

  • Updates an existing mto shipment
    • PATCH /mto-shipments/{mtoShipmentID}

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

Sample Input

{
  "mtoShipmentID": "05892b31-1374-4fbf-b9d8-184aa1a4ee7a",
  "ifMatch": "MjAyMC0wNC0zMFQwMTowNDowOS44NDkwOTha",
  "body": {
    "actualPickupDate": "0001-01-01",
    "agents": [
      {
        "agentType": "RELEASING_AGENT",
        "email": "[email protected]",
        "firstName": "Test",
        "id": "c89b32d8-0852-4490-890d-fc495812c8d4",
        "lastName": "Agent",
      }
    ],
    "destinationAddress": {
      "city": "Fairfield",
      "country": "US",
      "id": "9ad201fe-22de-40e2-a23a-1351f5690af2",
      "postalCode": "94535",
      "state": "CA",
      "streetAddress1": "987 Any Avenue",
      "streetAddress2": "P.O. Box 9876",
      "streetAddress3": "c/o Some Person"
    },
    "firstAvailableDeliveryDate": "0001-01-01",
    "pickupAddress": {...},
    "scheduledPickupDate": "2018-03-16",
    "secondaryDeliveryAddress": {...},
    "secondaryPickupAddress": {...},
    "shipmentType": "HHG"
  }
}

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. You'll need to decide which type of service item you wish to create first, and then create a json file modeled after the definition for that type.

Please see the Redoc for full details.

Command: create-mto-service-item

  • Creates a new MTO service item for a move task order and a shipment
    • POST /mto-service-items

Sample Input

  • Example MTO Service Item Shuttle Model Type:
{
  "body": {
    "reServiceCode": "DOSHUT",
    "modelType": "MTOServiceItemShuttle",
    "moveTaskOrderID": "da3f34cc-fb94-4e0b-1c90-ba3333cb7791",
    "mtoShipmentID": "15d360aa-c80a-4fca-9502-8540fd28b139",
    "reServiceName": "Test Create Service",
    "description": "testing shuttle",
    "reason": "shuttle reason"
  }
}
  • Example MTO Service Item DDFSIT Model Type:
{
  "body": {
    "reServiceCode": "DDFSIT",
    "modelType": "MTOServiceItemDDFSIT",
    "moveTaskOrderID": "da3f34cc-fb94-4e0b-1c90-ba3333cb7791",
    "mtoShipmentID": "15d360aa-c80a-4fca-9502-8540fd28b139",
    "reServiceName": "Test Create DDFSIT Service",
    "type": "FIRST",
    "timeMilitary1": "1430Z",
    "firstAvailableDeliveryDate1": "2020-05-24",
    "timeMilitary2": "1515Z",
    "firstAvailableDeliveryDate2": "2020-05-30"
  }
}
  • For more model types, please refer to the definitions in the API documentation.

Run

In your shell, run:

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

Sample Output

  • For MTO Service Item Shuttle example:
{
  "description": "testing shuttle",
  "reServiceCode": "DOSHUT",
  "reason": "shuttle reason",
  "eTag": "MjAyMC0wNS0xOVQxNjowMDoyOS4wNzc1NTJa",
  "id": "9c0a5174-29f9-44f2-b6d5-139c1ebbd6d9",
  "modelType": "MTOServiceItemShuttle",
  "moveTaskOrderID": "da3f34cc-fb94-4e0b-1c90-ba3333cb7791",
  "mtoShipmentID": "15d360aa-c80a-4fca-9502-8540fd28b139",
  "reServiceID": "d979e8af-501a-44bb-8532-2799753a5810",
  "rejectionReason": "shuttle reason",
  "status": "SUBMITTED"
}
  • For MTO Service Item DDFSIT example:
{
  "firstAvailableDeliveryDate1": "2020-05-24",
  "firstAvailableDeliveryDate2": "2020-05-30",
  "reServiceCode": "DDFSIT",
  "timeMilitary1": "1430Z",
  "timeMilitary2": "1515Z",
  "eTag": "MjAyMC0wNS0xOVQxNTo1Mzo0Ni4xNTE2Njha",
  "id": "2d382ff2-db03-4098-8fe7-6d3a0360b85d",
  "modelType": "MTOServiceItemDDFSIT",
  "moveTaskOrderID": "da3f34cc-fb94-4e0b-1c90-ba3333cb7791",
  "mtoShipmentID": "15d360aa-c80a-4fca-9502-8540fd28b139",
  "reServiceID": "d0561c49-e1a9-40b8-a739-3e639a9d77af",
  "status": "SUBMITTED"
}

Return to top

Clone this wiki locally