Kubernetes with OpenShift World Tour: Get hands-on experience and build applications fast! Find a workshop!

Learn how to use REST APIs to upload supply-chain platform data

What happens when all of your supply-chain processes are maintained in different systems, and you see that a batch of shipments to your most important customer will not be delivered on time? You can check to see where the problem is coming from, but since all of your data is stored on different systems, you’ll have to reach out to different managers, and it’ll take days before you can pinpoint the problem. By uploading data through APIs, all into one platform, you can have transparency into your supply chain and be notified before shipments arrive late to your customer.

IBM Sterling Supply Chain Insights With Watson® provides your organization with end-to-end visibility throughout all stages of the supply-chain lifecycle - from planning and sourcing to delivery and service and everything in between. Supply Chain Insights is a collaboration platform, enabling businesses to set up resolution rooms to discuss and take action on problems that inevitably arise during the supply-chain process. Now, Supply Chain Insights, like any other AI application, is only as good as the data that you give it. To make things simple, Supply Chain Insights allows for two ways to upload data into the platform: via an Excel sheet upload and via REST APIs, which we will cover here.

Note: This article assumes you have an IBM ID and a Supply Chain Insights trial account.

Accessing the Supply Chain Insights API keys

getkeys

Given that you are logged in with your IBM ID and have launched your IBM Sterling Supply Chain Insights platform, you are ready to upload some data. Let’s dive into how to get your API keys. From your operations center, look at the left-side navigation bar. Click on the Settings tab, which has an icon of a cog. From there, click on Build Info. There you will see two-thirds of the keys you need to access the APIs – the X-IBM-User-Secret and the X-IBM-Client-Id. Save these because you will need them later. Next, click on RESTPUL APIs right under API access. That will take you to the Supply Chain Insights API Documentation. As long as you are logged in with your IBM ID, you should see Supply Chain Insights in the middle of the page. You can then click on the key icon to manage your keys. This will expand the page, and you will see two icons: one with a lock and the other a key. If you hover your mouse over the keys, click the SHOW button and take note of the X-IBM-Client-Secret. You’re ready to make an API request!

Making your first GET request

getrequest

Let’s go ahead and make our first GET request. We’re going to use CURL to do this. Go ahead and download CURL if you don’t have it. Next, we will use an API to get all of the supply shipments we have available in our platform. Each trial account comes with dummy data, so you do not need to import anything.

There is a one-stop shop for Supply Chain API Documentation. From the left-hand tab, scroll down to supply shipments. Click on supply shipments > Find supply shipments. (You should be here now in the documentation.) You can see that this API request Retrieves the details for one or more supply shipments that match your query. Perfect! You can also see which header parameters are required – X-IBM-Client-Secret, X-IBM-Client-Id X-IBM-User-Secret.

Open a terminal, then copy and paste the following code, making sure to replace the client ID, client secret, and user secret with your own values:

curl -X GET \
  https://api.ibm.com/scinsights/run/api/supplyshipments \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-ibm-client-id: <your client id goes here>' \
  -H 'x-ibm-client-secret: <your client secret goes here>' \
  -H 'x-ibm-user-secret: <your user secret goes here>'

Your request should look like this, except your keys will be different:

curl -X GET \
  https://api.ibm.com/scinsights/run/api/supplyshipments \
  -H 'accept: application/json' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-ibm-client-id: 9e12d666-basasdf4b-4211-a540-2627bc0321b4' \
  -H 'x-ibm-client-secret: yD4cI3jO8asdfO2fG0wB3lF5uY7cQ4wM6lQ6oX8pN1bA8iF' \
  -H 'x-ibm-user-secret: a6f24a5d-055a-45c6fa09cec34'

Your output should look like this:

~$ curl -X GET \
>   https://api.ibm.com/scinsights/run/api/supplyshipments \
>   -H 'accept: application/json' \
>   -H 'cache-control: no-cache' \
>   -H 'content-type: application/json' \
>   -H 'x-ibm-client-id: 9e12d666-b14b-4210-2627bc0321b4' \
>   -H 'x-ibm-client-secret: yD4cI3jO8O2fG0wB3lF5uY7cQ4wM6lQ6oX8pN1bA8iF' \
>   -H 'x-ibm-user-secret: a6f24a5d-055a-b3e6-952c909cec34'
{"results":[{"_actualShipTime":"2019-02-28T00:00:00.000+0000","_actualTimeofArrival":null,"_airwayMasterNumber":null,"_billofLadingNumber":"BOL-ZB-PO-0001760","_carrierContainer":null,"_carrierID":"TransOceanic","_committedTimeofArrival":"2019-03-13T00:00:00.000+0000","_currentLocationCoordinates":null,"_currentRegion":null,"_dateCreated":"2019-02-08T00:00:00.000+0000","_destinationLocationID":"ZillaBar-NW-P","_estimatedTimeofArrival":"2019-03-13T00:00:00.000+0000","_eventMilestone":null,"_expectedPathofShipment":null,"_expeditedShipping":null,"_expeditedShippingCost":null,"_expeditedShippingCostCurrency":"US$","_freightForwarder":null,"_houseAirwayBill":null,"_id":"ZB-PO-0001760","_milestoneChangeTime":null,"_orderValue":279464.9446494465,"_originLocationID":"Bioway Organic Ingredients Co Ltd","_parcelTrackingNumber":null,"_predictedLocationofArrival":"ZillaBar-NW-P","_predictedTimeofArrival":"2019-03-13T00:00:00.000+0000","_previousEventMilestone":null,"_quantityCommitted":7650.0,"_quantityCommittedUOM":"Kilogram","_quantityShipped":7650.0,"_quantityShippedUOM":"Kilogram","_requestedShipDate":"2019-02-28T00:00:00.000+0000","_requestedTimeofArrival":"2019-03-13T00:00:00.000+0000","_revisedEstimatedTimeofArrival":null,"_shipmentNumber":"ZB-PO-0001760","_shippingCost":2794.6494464944653,"_shippingCostCurrency":"US$","_sourceLink":null,"_stop1":"Port of Los Angeles","_stop1ArrivalTime":"2.....

If you got some output that looks something like that, congratulations! You’ve just learned how to make your first API request to IBM Sterling Supply Chain Insights.

Making your first POST request

postrequest

Now it’s time to make a slightly more complicated API request: the POST request. The only difference in the request is that we send data enclosed in the body of the request message so that we have more control over exactly what we want to receive from the request.

So first, let’s make another GET request – this time GET/customers/{id}. This API finds a specific customer by ID in our platform. The documentation for this specific API can be found here.

The first request we will make will be to see if customer HoreaPorutiuDemo123 is in our platform; he should not be at first – i.e. the terminal have no response (this is what is expected):

curl -X GET \
  https://api.ibm.com/scinsights/run/api/customers/HoreaPorutiuDemo123 \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'x-ibm-client-id: 9e12d666-b14b-4211-a540-2627bc0321b4' \
  -H 'x-ibm-client-secret: yD4cI3jO8tE3wN7hO2fG0wB3lF5uY7cQ4wM6lQ6oX8pN1bA8iF' \
  -H 'x-ibm-user-secret: a6f24a5d-055a-45c6-b3e6-952c909cec34'

Next, let’s make a POST request to add that customer into our platform:

curl -X POST \
  https://api.ibm.com/scinsights/run/api/customers \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'x-ibm-client-id: 9e12d666-b14b-4211-a540-2627bc0321b4' \
  -H 'x-ibm-client-secret: yD4cI3jO8tE3wN7hO2fG0wB3lF5uY7cQ4wM6lQ6oX8pN1bA8iF' \
  -H 'x-ibm-user-secret: a6f24a5d-055a-45c6-b3e6-952c909cec34' \
  -d '{
 "_id": "HoreaPorutiuDemo123",
  "division": "Computer Services",
  "location": "San Francisco",
  "name": "Horea Porutiu LLC"
}
'

Again, if you get no response in your terminal, that’s good. If you try the same request twice, you should get an error that says {"error":"Cannot create resource. A resource with the same ID already exists. This is normal because the only requirement for creating a new object in our Supply Chain Insights platform is using a unique ID each time. We want objects to be easily queried.

So let’s query again for customer HoreaPorutiuDemo123, which we just added by POST request. This should finally work! Use that same request again:

curl -X GET \
  https://api.ibm.com/scinsights/run/api/customers/HoreaPorutiuDemo123 \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'x-ibm-client-id: 9e12d666-b14b-4211-a540-2627bc0321b4' \
  -H 'x-ibm-client-secret: yD4cI3jO8tE3wN7hO2fG0wB3lF5uY7cQ4wM6lQ6oX8pN1bA8iF' \
  -H 'x-ibm-user-secret: a6f24a5d-055a-45c6-b3e6-952c909cec34'

This time, you should get the following JSON back in your terminal:

{"_id":"HoreaPorutiuDemo123",
"createSkeleton":false,
"deleteSkeleton":false,
"division":"Computer Services",
"lastUpdatedByFeed":null,
"location":"San Francisco",
"meta":null,
"name":"Horea Porutiu LLC",
"recordCreated":"2019-10-02T19:25:15.683+0000",
"sci_dataLastUpdated":null,
"source":null,
"sourceLink":null}

Nice job! You now know how to make a POST request using the IBM Sterling Supply Chain Insights APIs. This is just a getting started guide, but it should at least whet your appetite. Going forward, you can use Cloud microservices such as Cloud Functions to automate the uploading of data into the platform, but this serves as a good foundation to understand how to use the APIs. Happy learning!

Horea Porutiu