CubeMaster API Integration Guide

A RESTful API (Representational State Transfer) is a way for applications to communicate over the internet using standard HTTP methods like GET, POST, PUT, and DELETE. Here’s a simple breakdown:

• Endpoint: A URL (e.g., https://api.cubemaster.net/loads) where the API can be accessed.
• HTTP Methods: Actions you can perform:
  • GET: Retrieve data.
  • POST: Send data to create something (like building a load in this case).
• JSON: A lightweight format for sending and receiving data (you’ll see examples below).
• Headers: Extra info sent with the request, like your API key for authentication.

In this guide, we’ll use the POST method to send a JSON payload to https://api.cubemaster.net/loads to create a load plan.

Create a Google Cloud project to host your API integration.

1. Go to Google Cloud Console and sign in.
2. Click the project dropdown at the top and select New Project.
3. Enter a project name (e.g., "CubeMasterIntegration"), choose a billing account, and click Create.
4. Once created, select the project from the dropdown to enter its dashboard.
5. In the left sidebar, navigate to APIs & Services > Credentials to manage authentication (though we’ll use the CubeMaster TokenID here).

Your customer’s orders or shipments data (e.g., cargo details) may be stored in a legacy database. Extract this data to build the API request.

1. Connect to your legacy database (e.g., MySQL, Oracle) using a tool like Google Cloud SQL or a local client.
2. Run a query to fetch relevant fields (e.g., item name, dimensions, weight, quantity). Example SQL:

   SELECT name, length, width, height, weight, quantity FROM shipments WHERE order_id = '12345';

3. Map the data to the CubeMaster API’s Cargoes structure. For example, if your database returns:
   • Name: "ITEM001", Length: 72, Width: 30, Height: 75, Weight: 1002.45, Quantity: 16
   Convert it to JSON like:

   {
       "Name": "ITEM001",
       "Length": 72,
       "Width": 30,
       "Height": 75,
       "Weight": 1002.45,
       "Qty": 16,
       "OrientationsAllowed": "OrientationsAll",
       "TurnAllowedOnFloor": false,
       "ColorKnownName": "Brown"
   }

4. Repeat for all items and include them in the Cargoes array of the request JSON.

Use Google Cloud Functions to make the POST request to the CubeMaster API.

1. In the Google Cloud Console, go to Cloud Functions in the left sidebar.
2. Click Create Function.
3. Configure the function:
   • Name: "callCubeMasterAPI"
   • Region: Choose your preferred region (e.g., us-central1).
   • Trigger: HTTP (to allow external calls).
   • Authentication: Allow unauthenticated (for testing; secure it later).
4. Click Next, then select Node.js as the runtime.
5. In the code editor, replace the default code with:

   const functions = require('@google-cloud/functions-framework');
   const axios = require('axios');
   
   functions.http('callCubeMasterAPI', async (req, res) => {
       const apiKey = 'YOUR_API_KEY_HERE'; // Replace with your CubeMaster API key
       const url = 'https://api.cubemaster.net/loads';
       const requestData = {
           "Title": "New Mixed Truck Load",
           "Description": "Hello Web API",
           "Cargoes": [
               {
                   "Name": "ITEM001",
                   "Length": 72,
                   "Width": 30,
                   "Height": 75,
                   "Weight": 1002.45,
                   "OrientationsAllowed": "OrientationsAll",
                   "TurnAllowedOnFloor": false,
                   "Qty": 16,
                   "ColorKnownName": "Brown"
               },
               {
                   "Name": "ITEM002",
                   "Length": 27.31,
                   "Width": 37.5,
                   "Height": 76.67,
                   "Weight": 521.45,
                   "OrientationsAllowed": "OrientationsAll",
                   "TurnAllowedOnFloor": false,
                   "Qty": 28,
                   "ColorKnownName": "Aqua"
               },
               {
                   "Name": "SKU0005",
                   "Length": 27.31,
                   "Width": 9.5,
                   "Height": 75.67,
                   "Weight": 501.45,
                   "OrientationsAllowed": "OrientationsAll",
                   "TurnAllowedOnFloor": true,
                   "Qty": 24,
                   "ColorKnownName": "Beige"
               },
               {
                   "Name": "SKU0005",
                   "Qty": 23
               },
               {
                   "Name": "SKU0008",
                   "Qty": 34
               }
           ],
           "Containers": [
               {
                   "VehicleType": "Dry",
                   "Name": "53FT-Intermodal",
                   "Length": 630,
                   "Width": 98,
                   "Height": 106,
                   "ColorKnownName": "Blue"
               }
           ],
           "Rules": {
               "IsWeightLimited": true,
               "IsSequenceUsed": false,
               "FillDirection": "FrontToRear",
               "CalculationType": "MixLoad"
           }
       };
   
       try {
           const response = await axios.post(url, requestData, {
               headers: {
                   'TokenID': apiKey,
                   'Content-Type': 'application/json'
               }
           });
           res.status(200).json(response.data);
       } catch (error) {
           res.status(500).json({ error: error.message });
       }
   });

6. In the package.json tab, add the axios dependency:

   {
       "dependencies": {
           "@google-cloud/functions-framework": "^3.0.0",
           "axios": "^1.6.0"
       }
   }

7. Click Deploy and wait for the function to be created. You’ll get a URL (e.g., https://us-central1-yourproject.cloudfunctions.net/callCubeMasterAPI).

Request JSON Example:

{
    "Title": "New Mixed Truck Load",
    "Description": "Hello Web API",
    "Cargoes": [
        {
            "Name": "ITEM001",
            "Length": 72,
            "Width": 30,
            "Height": 75,
            "Weight": 1002.45,
            "OrientationsAllowed": "OrientationsAll",
            "TurnAllowedOnFloor": false,
            "Qty": 16,
            "ColorKnownName": "Brown"
        }
    ],
    "Containers": [
        {
            "VehicleType": "Dry",
            "Name": "53FT-Intermodal",
            "Length": 630,
            "Width": 98,
            "Height": 106,
            "ColorKnownName": "Blue"
        }
    ],
    "Rules": {
        "IsWeightLimited": true,
        "IsSequenceUsed": false,
        "FillDirection": "FrontToRear",
        "CalculationType": "MixLoad"
    }
}

After calling the API, process the response to extract useful information.

1. Check the status field to confirm success ("succeed").
2. If there’s an error, inspect calculationError (e.g., "InvalidCargoSize") and log it.
3. Extract key data from loadSummary:
   • cargoesLoaded: Number of items loaded (e.g., 68).
   • volumeUtilization: Container space used (e.g., 80.39%).
   • weightLoaded: Total weight (e.g., 42674.60).
4. Use filledContainers.graphics.images URLs (e.g., path3DDiagram) to display load diagrams.
5. Save the response to Google Cloud Storage or a database (e.g., Firestore) for later use:
   • Go to Cloud Storage, create a bucket (e.g., "cubemaster_responses").
   • Modify the Cloud Function to upload response.data using the @google-cloud/storage package.

Response JSON Example:

{
    "status": "succeed",
    "message": "Engine created. 5 cargoes. 1 empty containers. Calculation started. Calculation ended. The load built successfully. The load saved to the cloud database.",
    "calculationError": "InvalidCargoSize",
    "document": {
        "title": "New Mixed Truck Load",
        "description": "Hello Web API",
        "calculationTimeInSeconds": 0.6152743,
        "createdBy": "CHANG@LOGEN.CO.KR",
        "createdAt": "2023-02-11T01:17:01.7392204+09:00"
    },
    "loadSummary": {
        "cargoesLoaded": 68,
        "piecesLoaded": 68,
        "volumeLoaded": 5261723.4606,
        "weightLoaded": 42674.59999999999
    },
    "filledContainers": [
        {
            "name": "#1 53FT-Intermodal",
            "loadSummary": {
                "volumeUtilization": 80.39990374424703,
                "weightLoaded": 42674.59999999999
            },
            "graphics": {
                "images": {
                    "path3DDiagram": "https://api.cubemaster.net/runtimes/b28413ca_51ed_44c9_b92e_13147363fd61.PNG"
                }
            }
        }
    ]
}

Use Google Cloud tools to monitor and debug your API integration.

1. Go to Cloud Functions in the Google Cloud Console.
2. Select your function (e.g., "callCubeMasterAPI") and click the Logs tab to view execution logs.
3. Check for errors (e.g., "500 Internal Server Error") and inspect the stack trace or error message.
4. Enable Cloud Monitoring:
   • Navigate to Monitoring in the sidebar.
   • Create a dashboard and add metrics like "Function Execution Count" or "Execution Time".
5. Use Cloud Debugger to set breakpoints in your code:
   • Go to Debugger, select your function, and add breakpoints to inspect variables (e.g., response.data).
6. Test the function manually by visiting its URL in a browser or using a tool like Postman with the provided trigger URL.