Skip to content
This repository has been archived by the owner on Oct 21, 2021. It is now read-only.

Trace API

Jump to bottom
Wuchieh J. Jong edited this page May 3, 2019 · 11 revisions

Trace API

The Trace API allows you to retrieve information from IBM Food Trust™ for events, products, locations, and associated data.

Attention: The Trace API Documentation (April 2019) PDF file is provided as a supplement to this page, and includes detailed examples.

Contents

  1. Prerequisites
  2. Getting Started
  3. Swagger
  4. Trace API
    1. Parameters
    2. Example Query
    3. Response Model
    4. Events
    5. Facilities
    6. Payloads
    7. Product Instances
    8. Products
  5. Products API
    1. Parameters
    2. Example Query
    3. Response Model
  6. Product Instances API
    1. Parameters
    2. Example Query
    3. Response Model

Prerequisites

To use the IBM Food Trust Outbound API, you must meet the following prerequisites:

  1. Your organization must have subscribed to the IBM Food Trust Trace module; please contact Aditya Khosla by email at [email protected] for details.

  2. You are familiar with using REST APIs to send data programmatically. Automation of data upload is an ultimate goal for you and your supply chain partners to maximize the value of IBM Food Trust.

  3. For IBM Food Trust organizations to share and trace supply chain data, each organization must have defined the appropriate data access control. For details on restricting and sharing your data, see Data Entitlement and Access Control.

Getting Started

Take the following steps to get started with the IBM Food Trust Outbound API:

  1. Obtain an Authentication Token - Get Authentication Token for Human User or Get Authentication Token for System User.

  2. Submit an API request with the authentication token in the Authorization header. See an example request for the Trace API here. For manual testing, human users can use the Swagger UI to run the APIs directly.

  3. Refer to the API endpoint documentation below for help understanding the response format.

Swagger

Swagger can be used in the development process to test the API endpoints. Our Swagger UI is available in the following environments:

To try out the API manually, you must first provide a valid IBM Food Trust Authorization Token (human user token) in the Swagger page, using the Authorize button on the top right of the page.

Endpoints

/ift/api/outbound/v1/traces

The traces endpoint retrieves trace information based on a product identifier.

Traces Parameters

The following parameters are supported:

productId (query string)

A parameter that identifies the specific product instance to retrieve trace information for. The supported formats are shown in the following table:

Type Example and Syntax
EPC LGTIN urn:epc:class:lgtin:0614141.107346.101
urn:epc:class:lgtin:<CompanyPrefix>.<ItemRefAndIndicator>.<Lot>(13 digits + Lot #)
EPC SGTIN urn:epc:id:sgtin:0614141.107346.2017
urn:epc:id:sgtin:<CompanyPrefix>.<ItemRefAndIndicator>.<SerialNumber>(13 Digits + Serial Number)
IBM Food Trust™ Product with Lot # urn:ibm:ift:product:lot:class:1234567890123.product-123.lot4
urn:ibm:ift:product:lot:class:<Company Prefix>.<Item Reference>.<Lot Number>
IBM Food Trust™ Product with Serial # urn:ibm:ift:product:serial:obj:1234567890123.product-123.serial-number-4567
urn:ibm:ift:product:serial:obj:<Company Prefix>.<Item Reference>.<Serial Number>

Traces Example Query

Request:

curl -X GET "https://eu.food.ibm.com/ift/api/outbound/v1/traces?productId=urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-1" -H "accept: application/json" -H "Authorization: Bearer <VALID_IFT_AUTHORIZATION_TOKEN>"

Response:

{
  "urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-1": {
    "events": {
      "urn:uuid:c50240fc-4df3-4d34-bd16-36031bf8b2a5": {
        "data": {
          "time": "2018-10-28T00:00:00.000Z",
          "type": "commission",
          "step": "urn:epcglobal:cbv:bizstep:commissioning",
          "facility": {
            "id": "urn:ibm:ift:location:loc:999999999999.farm-1"
          },
          "productInstances": {
            "instances": [
              {
                "id": "urn:ibm:ift:product:lot:class:999999999999.mango.lot-1",
                "quantity": 500,
                "unit": "CS"
              }
            ]
          }
        },
        "payloadIds": []
      },
      "urn:uuid:b3b8ee28-58cb-4f26-9ad5-f27b27cb89d6": {
        "data": {
          "time": "2018-10-29T02:00:00.000Z",
          "type": "commission",
          "step": "urn:epcglobal:cbv:bizstep:commissioning",
          "facility": {
            "id": "urn:ibm:ift:location:loc:999999999999.farm-2"
          },
          "productInstances": {
            "instances": [
              {
                "id": "urn:ibm:ift:product:lot:class:999999999999.mango.lot-2",
                "quantity": 650,
                "unit": "CS"
              }
            ]
          }
        },
        "payloadIds": []
      },
      "urn:uuid:7d87bbfd-e9b0-49ee-9c04-d2938f6138f8": {
        "data": {
          "time": "2018-11-02T00:00:01.000Z",
          "type": "transformation",
          "step": "urn:epcglobal:cbv:bizstep:transforming",
          "facility": {
            "id": "urn:ibm:ift:location:loc:999999999999.factory-1"
          },
          "productInstances": {
            "inputs": [
              {
                "id": "urn:ibm:ift:product:lot:class:999999999999.mango.lot-1",
                "quantity": 500,
                "unit": "CS"
              },
               {
                "id": "urn:ibm:ift:product:lot:class:999999999999.mango.lot-2",
                "quantity": 650,
                "unit": "CS"
              }
            ],
            "outputs": [
              {
                "id": "urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-2",
                "quantity": 4800,
                "unit": "KGM"
              }
            ]
          }
        },
        "payloadIds": []
      },
      "urn:uuid:e207acb5-139b-4813-98bf-b275775e499f": {
        "data": {
          "time": "2018-11-12T00:00:01.000Z",
          "type": "observation",
          "step": "urn:epcglobal:cbv:bizstep:stocking",
          "facility": {
            "id": "urn:ibm:ift:location:loc:5555555555555.store-1",
            "sources": [
              {
                "id": "urn:ibm:ift:location:loc:999999999999.factory-1"
              }
            ],
            "destinations": [
              {
                "id": "urn:ibm:ift:location:loc:5555555555555.store-1"
              }
            ]
          },
          "productInstances": {
            "instances": [
              {
                "id": "urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-2",
                "quantity": 1,
                "unit": "EA"
              }
            ]
          }
        },
        "payloadIds": []
      }
    },
    "facilities": {
      "urn:ibm:ift:location:loc:999999999999.farm-1": {
        "data": {
          "name": "Tropical Farms",
          "type": "FARM",
          "address": {
            "city": "Miami",
            "postalCode": "72814"
          }
        }
      },
      "urn:ibm:ift:location:loc:999999999999.farm-2": {
        "data": {
          "name": "Sunshine Farms",
          "type": "FARM",
          "address": {
            "city": "West Palm Beach",
            "postalCode": "33401"
          }
        }
      },
      "urn:ibm:ift:location:loc:999999999999.factory-1": {
        "data": {
          "name": "LC Foods Inc",
          "type": "PROCESSING_FACILITY",
          "address": {
            "city": "Florence",
            "postalCode": "29501"
          }
        },
        "payloadIds": []
      },
      "urn:ibm:ift:location:loc:5555555555555.store-1": {
        "data": {
          "name": "Bob's Corner Market",
          "type": "STORE",
          "address": {
            "street": "1 Main St",
            "city": "Durham",
            "state": "NC",
            "postalCode": "27713",
            "country": "US"
          }
        },
        "payloadIds": []
      }
    },
    "payloads": {
      "urn:uuid:eed87696-40cc-4839-a609-24d8f0429d08": {
        "data": {
          "time": "2018-11-02T00:00:00.000Z",
          "content": "[]",
          "contentType": "application/json",
          "typeUri": "typeUriString"
        }
      }
    },
    "productInstances": {
      "urn:ibm:ift:product:lot:class:999999999999.mango.lot-1": {
        "data": {
          "name": "Mango",
          "productId": "urn:ibm:ift:product:class:999999999999.mango"
        },
        "payloadIds": []
      },
       "urn:ibm:ift:product:lot:class:999999999999.mango.lot-2": {
        "data": {
          "name": "Mango",
          "productId": "urn:ibm:ift:product:class:999999999999.mango"
        },
        "payloadIds": []
      },
      "urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-2": {
        "data": {
          "name": "Sliced Mango",
          "productId": "urn:ibm:ift:product:class:999999999999.sliced-mango",
          "sellByDate": "2018-11-17"
        },
        "payloadIds": [
          "urn:uuid:eed87696-40cc-4839-a609-24d8f0429d08"
        ]
      }
    },
    "products": {
      "urn:ibm:ift:product:class:999999999999.mango": {
        "data": {
          "name": "Mango"
        },
        "payloadIds": []
      },
      "urn:ibm:ift:product:class:999999999999.sliced-mango": {
        "data": {
          "name": "Sliced Mango",
          "sku": "12345678"
        },
        "payloadIds": []
      }
    }
  },
  "x-version": "1.0.0"
}

Traces Response Model

The Traces API returns data pertaining to events, locations, data payloads, and products in the following JSON format:

{
  "<TRACE_PRODUCT_ID>": {
    "events": {
      <EVENT_OBJECTS>
    },
    "facilities": {
      <FACILITY_OBJECTS>
    },
    "payloads": {
      <PAYLOAD_OBJECTS>
    },
    "product_instances": {
      <PRODUCT_INSTANCE_OBJECTS>
    },
    "products: {
      <PRODUCT_OBJECTS>
    }
  },
  "x-version": "<VERSION>"
}

For each JSON object, the data Model and Example JSON are provided below:

Events

Events related to the specified trace product identifier are returned in the events section of the JSON response. By default, only the following types of events are returned:

  • Lot Creation - Events that contain information collected during the lot creation of products.
    • Lot Creation events must meet the following criteria:
      • Event Type: Commission
  • Transformation - Events that contain information collected when input products are transformed into intermediate or finished products.
    • Transformation events must meet the following criteria:
      • Event Type: Transformation
  • Store Scan - Events that contain information collected when the product is scanned at a store.
    • Store Scan events must meet the following criteria:
      • Event Type: Observation
      • Biz Step: Stocking

Model:

"events": {
  // Unique ID of the event
  "<EVENT_ID>": {
    "data": {
      // Date and time of the event in the format: "yyyy-mm-ddThh:mm:ss.mmmZ"
      "time": "<EVENT_TIME>",
      // Type of business transaction (commission, transformation, observation)
      "type": "<EVENT_TYPE>",
      // Business step that the event was a part of in the format: "urn:epcglobal:cbv:bizstep:Step"
      "step": "<EVENT_STEP>",
      "facility": {
        // Unique ID of the facility
        "id": "<FACILITY_ID>",
        "sources": [
          {
            // Unique ID of the source facility
            "id": "<SOURCE_ID>"
          }
        ],
        "destinations": [
          {
            // Unique ID of the destination facility
            "id": "<DESTINATION_ID>"
          }
        ]
      },
      "productInstances": {
        "instances": [
          {
            // Unique ID of the instance
            "id": "<INSTANCE_ID>",
            // Item quantity must be a number
            "quantity": <INSTANCE_QUANTITY>,
            // Unit of measure is a two or three character code from UN/CEFACT
            "unit": "<INSTANCE_UNIT_OF_MEASURE>"
          }
        ],
        "inputs": [
          { 
            // Unique ID of the input
            "id": "<INPUT_ID>",
            // Input quantity must be a number
            "quantity": <INPUT_QUANTITY>,
            // Unit of measure is a two or three character code from UN/CEFACT
            "unit": "<INPUT_UNIT_OF_MEASURE>"
          }
        ],
        "outputs": [
          {
            // Unique ID of the output
            "id": "<OUTPUT_ID>",
            "quantity": <OUTPUT_QUANTITY>,
            // Unit of measure is a two or three character code from UN/CEFACT
            "unit": "<OUTPUT_UNIT_OF_MEASURE"
          }
        ]
      }
    },
    // List of associated Payload IDs
    "payloadIds": [
      <PAYLOAD_IDS>
    ]
  },

Example:

"events": {
  "urn:uuid:c50240fc-4df3-4d34-bd16-36031bf8b2a5": {
    "data": {
      "time": "2018-10-28T00:00:00.000Z",
      "type": "commission",
      "step": "urn:epcglobal:cbv:bizstep:commissioning",
      "facility": {
        "id": "urn:ibm:ift:location:loc:999999999999.farm-1"
      },
      "productInstances": {
        "instances": [
          {
            "id": "urn:ibm:ift:product:lot:class:999999999999.mango.lot-1",
            "quantity": 500,
            "unit": "CS"
          }
        ]
      }
    },
    "payloadIds": []
  },
  "urn:uuid:b3b8ee28-58cb-4f26-9ad5-f27b27cb89d6": {
    "data": {
      "time": "2018-10-29T02:00:00.000Z",
      "type": "commission",
      "step": "urn:epcglobal:cbv:bizstep:commissioning",
      "facility": {
        "id": "urn:ibm:ift:location:loc:999999999999.farm-2"
      },
      "productInstances": {
        "instances": [
          {
            "id": "urn:ibm:ift:product:lot:class:999999999999.mango.lot-2",
            "quantity": 650,
            "unit": "CS"
          }
        ]
      }
    },
    "payloadIds": []
  },
  "urn:uuid:7d87bbfd-e9b0-49ee-9c04-d2938f6138f8": {
    "data": {
      "time": "2018-11-02T00:00:01.000Z",
      "type": "transformation",
      "step": "urn:epcglobal:cbv:bizstep:transforming",
      "facility": {
        "id": "urn:ibm:ift:location:loc:999999999999.factory-1"
      },
      "productInstances": {
        "inputs": [
          {
            "id": "urn:ibm:ift:product:lot:class:999999999999.mango.lot-1",
            "quantity": 500,
            "unit": "CS"
          },
            {
            "id": "urn:ibm:ift:product:lot:class:999999999999.mango.lot-2",
            "quantity": 650,
            "unit": "CS"
          }
        ],
        "outputs": [
          {
            "id": "urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-2",
            "quantity": 4800,
            "unit": "KGM"
          }
        ]
      }
    },
    "payloadIds": []
  },
  "urn:uuid:e207acb5-139b-4813-98bf-b275775e499f": {
    "data": {
      "time": "2018-11-12T00:00:01.000Z",
      "type": "observation",
      "step": "urn:epcglobal:cbv:bizstep:stocking",
      "facility": {
        "id": "urn:ibm:ift:location:loc:5555555555555.store-1",
        "sources": [
          {
            "id": "urn:ibm:ift:location:loc:999999999999.factory-1"
          }
        ],
        "destinations": [
          {
            "id": "urn:ibm:ift:location:loc:5555555555555.store-1"
          }
        ]
      },
      "productInstances": {
        "instances": [
          {
            "id": "urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-2",
            "quantity": 1,
            "unit": "EA"
          }
        ]
      }
    },
    "payloadIds": []
  }
}

Facilities

Facility information related to a product trace is contained in the facilities block. The model is shown below:

Model:

"facilities": {
  // Unique ID for the facility
  "<FACILITY_ID>": {
    "data": {
      "name": "<FACILITY_NAME>",
      // Type of facility (STORE, FARM, SUPPLIER, etc)
      "type": "STORE",
      "address": {
        "street": "<FACILITY_STREET_ADDRESS>",
        "city": "<FACILITY_CITY>",
        "state": "<FACILITY_STATE>",
        "postalCode": "<FACILITY_POSTAL_CODE>",
        "country": "<FACILTIY_COUNTRY>"
      }
    },
    // List of associated Payload IDs
    "payloadIds": [
      <PAYLOAD_IDS>
    ]
  }
}

Example:

"facilities": {
  "urn:ibm:ift:location:loc:999999999999.farm-1": {
    "data": {
      "name": "Tropical Farms",
      "type": "FARM",
      "address": {
        "city": "Miami",
        "postalCode": "72814"
      }
    }
  },
  "urn:ibm:ift:location:loc:999999999999.farm-2": {
    "data": {
      "name": "Sunshine Farms",
      "type": "FARM",
      "address": {
        "city": "West Palm Beach",
        "postalCode": "33401"
      }
    }
  },
  "urn:ibm:ift:location:loc:999999999999.factory-1": {
    "data": {
      "name": "LC Foods Inc",
      "type": "PROCESSING_FACILITY",
      "address": {
        "city": "Florence",
        "postalCode": "29501"
      }
    },
    "payloadIds": []
  },
  "urn:ibm:ift:location:loc:5555555555555.store-1": {
    "data": {
      "name": "Bob's Corner Market",
      "type": "STORE",
      "address": {
        "street": "1 Main St",
        "city": "Durham",
        "state": "NC",
        "postalCode": "27713",
        "country": "US"
      }
    },
    "payloadIds": []
  }
}

Payloads

Payloads contain custom information related to a product trace in the payloads block. One or more trace events, facilities, products, or product instances can reference a payload ID in the payloadIds. The model is shown below:

Model:

"payloads": {
  // Unique ID of the payload
  "<PAYLOAD_ID>": {
    "data": {
      // Date and time of the payload in the format: "yyyy-mm-ddThh:mm:ss.mmmZ"
      "time": "<PAYLOAD_TIME>",
      // Customized content in a String format
      "content": "<PAYLOAD_CONTENT>",
      // HTTP content type of the payload (application/json, application/xml, etc)
      "contentType": "<PAYLOAD_CONTENT_TYPE>",
      // URI for the payload type
      "typeUri": "<PAYLOAD_TYPE_URI>"
    }
  }
}

Example:

"payloads": {
  "urn:uuid:eed87696-40cc-4839-a609-24d8f0429d08": {
    "data": {
      "time": "2018-11-02T00:00:00.000Z",
      "content": "customized data",
      "contentType": "application/json",
      "typeUri": "typeUriString"
    }
  }
}

Product Instances

Product instance (such as lot-level) information related to a product trace is contained in the productInstances block. A productInstance is a specific instance or lot of a product. The model is shown below:

Model:

"productInstances": {
  // Unique ID of the product instance
  "<PRODUCT_INSTANCE_ID>: {
    "data": {
      "name": "<PRODUCT_NAME>",
      "productId": "<PRODUCT_ID>",
      // Date of freeze in YYYY-MM-DD format
      "firstFreezeDate": "<DATE>",
      // Date of the start of harvest in YYYY-MM-DD format
      "harvestStartDate": "<DATE>",
      // Date of the end of harvest in YYYY-MM-DD format
      "harvestEndDate": "<DATE>",
      // Expiration date in YYYY-MM-DD format
      "expirationDate": "<DATE>",
      // Sell-by date in YYYY-MM-DD format
      "sellByDate": "<DATE>"
    },
    // List of associated Payload IDs
    "payloadIds": [
      <PAYLOAD_IDS>
    ]
  },
}

Example:

"productInstances": {
  "urn:ibm:ift:product:lot:class:999999999999.mango.lot-1": {
    "data": {
      "name": "Mango",
      "productId": "urn:ibm:ift:product:class:999999999999.mango"
    },
    "payloadIds": []
  },
    "urn:ibm:ift:product:lot:class:999999999999.mango.lot-2": {
    "data": {
      "name": "Mango",
      "productId": "urn:ibm:ift:product:class:999999999999.mango"
    },
    "payloadIds": []
  },
  "urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-2": {
    "data": {
      "name": "Sliced Mango",
      "productId": "urn:ibm:ift:product:class:999999999999.sliced-mango",
      "sellByDate": "2018-11-17"
    },
    "payloadIds": [
      "urn:uuid:eed87696-40cc-4839-a609-24d8f0429d08"
    ]
  }
}

Products

General product information is contained in the product block. The model is shown below:

Model:

"products": {
  // Unique ID of the product
  "<PRODUCT_ID>": {
    "data": {
      "name": "<PRODUCT_NAME>",
      "sku": "<PRODUCT_SKU>"
    },
    // List of associated Payload IDs
    "payloadIds": [
      <PAYLOAD_IDS>
    ]
  }
}

Example:

"products": {
  "urn:ibm:ift:product:class:999999999999.mango": {
    "data": {
      "name": "Mango"
    },
    "payloadIds": []
  },
  "urn:ibm:ift:product:class:999999999999.sliced-mango": {
    "data": {
      "name": "Sliced Mango",
      "sku": "12345678"
    },
    "payloadIds": []
  }
}

/ift/api/outbound/v1/products

The products endpoint retrieves a list of products. By default, the endpoint is limited to returning a maximum of 500 products.

Products Parameters

orgId (optional query string array)

A parameter that restricts results to products matching organization IDs. By default, the submitter's organization ID is used.

limit (optional query number)

A parameter that limits the number of products returned. Valid range of integer values is 1 thru 1000. The default is 500.

skip (optional query number)

A parameter that specifies the number of products to skip when searching for products to return. Valid range of integer values is 0 thru 9000. The default is 0.

Products Example Query

Request:

curl -X GET "https://eu.food.ibm.com/ift/api/outbound/v1/products?orgId=de035c22-8308-4e89-8186-7f81660e7fa5&orgId=a2260194-11a6-4a02-baf6-eee5f1254c5b" -H "accept: application/json" -H "Authorization: Bearer <VALID_IFT_AUTHORIZATION_TOKEN>"

Response:

{
  "products": {
    "de035c22-8308-4e89-8186-7f81660e7fa5": {
      "urn:ibm:ift:product:class:5964299096683.29394": {
        data: {
            "name": "Whole Chicken",
            "sku": "B0M6CI82P35"
        }           
      },
      "urn:ibm:ift:product:class:8026366486370.88747": {
        data: {
            "name": "Tomatoes 1Kg",
            "sku": "14d856d423d588ef7e311c3b48e817b7"
        }           
      }
    },
    "a2260194-11a6-4a02-baf6-eee5f1254c5b": {
      "00026625117220": {
        data: {
            "name": "Potatoes 1Kg",
            "sku": "14d856d423d588ef7e311c3b48e817b7"
        }           
      },
      "urn:ibm:ift:product:class:7508737668055.BestMango": {
        data: {
            "name": "Best Mango",
            "sku": "9a8f75e1b8903782f1630ac2d6cfebe2"
        }           
      }
    }
  },
  "x-version": "1.0.0"
}

Products Response Model

The Products API returns data pertaining to products in the following JSON format:

{
  "products": {
    // Unique Organization Id
    "<ORG_A_ID>":{
      // Unique Product Id
      "<PRODUCT_A_ID>": {
        "data": {
          // Product Name
          "name": "<PRODUCT_A_NAME>",
          // Product SKU
          "sku:": "<PRODUCT_A_SKU>"
        }
      },
      // Unique Product Id
      "<PRODUCT_B_ID>": {
        "data": {
          // Product Name
          "name": "<PRODUCT_B_NAME>",
          // Product SKU
          "sku:": "<PRODUCT_B_SKU>"
        }
      }  
    },
    // Unique Organization Id
    "<ORG_B_ID>":{
      // Unique Product Id
      "<PRODUCT_C_ID>": {
        "data": {
          // Product Name
          "name": "<PRODUCT_C_NAME>",
          // Product SKU
          "sku:": "<PRODUCT_C_SKU>"
        }
      },
      // Unique Product Id
      "<PRODUCT_D_ID>": {
        "data": {
          // Product Name
          "name": "<PRODUCT_D_NAME>",
          // Product SKU
          "sku:": "<PRODUCT_D_SKU>"
        }
      }  
    }
  }
}

/ift/api/outbound/v1/productInstances

The product instances endpoint retrieves a list of product instances (lots and serials). By default, the endpoint is limited to returning a maximum of 500 product instances. The results are sorted from most recent to least recent based on last modified date.

Product Instances Parameters

productId (query string array)

A parameter that identifies the specific product identifiers that the user wants to retrieve product instances information on. Product identifiers must be in the EPC-GTIN or Food Trust product identifier format. Supported formats are shown in the following table.

Type Example
GS1-GTIN 00668537437807 (14 Digits)
IFT Product Identifier urn:ibm:ift:product:class:0614141.107346
urn:ibm:ift:product:class:<Company Prefix>.<Item Reference>

startTime (optional query string)

A parameter that restricts results to new or updated product instances on or after time in ISO 8601 format. By default, it is set to start of epoch time.

endTime (optional query string)

A parameter that restricts results to new or updated product instances before time in ISO 8601 format. By default, it is set to now.

limit (optional query number)

A parameter that limits the number of products returned. Valid range of integer values is 1 thru 1000. The default is 500.

skip (optional query number)

A parameter that specifies the number of products to skip when searching for products to return. Valid range of integer values is 0 thru 9000. The default is 0.

Product Instances Example Query

Request:

curl -X GET "https://eu.food.ibm.com/ift/api/outbound/v1/productInstances?productId=05481386759785&productId=00452246787922" -H "accept: application/json" -H "Authorization: Bearer <VALID_IFT_AUTHORIZATION_TOKEN>"

Response:

{
  "productInstances": {
    "urn:ibm:ift:product:class:1234567890123.raspberry": [
      "urn:ibm:ift:product:lot:class:1234567890123.raspberry.3-0",
      "urn:ibm:ift:product:lot:class:1234567890123.raspberry.72-0",
      "urn:ibm:ift:product:lot:class:1234567890123.raspberry.72-1"
    ],
    "00452246787922": [
      "urn:epc:class:lgtin:045224.0678792.L2002",
      "urn:epc:class:lgtin:045224.0678792.L1002",
      "urn:epc:class:lgtin:045224.0678792.L407",
      "urn:epc:class:lgtin:045224.0678792.L102"
    ]
  }
  "x-version": "1.0.0"
}

Product Instances Response Model

The Product Instances API returns data pertaining to product instances in the following JSON format:

{
  "productInstances": { 
    // Unique ID of the product
    "<PRODUCT_ID_A>": [
      // Unique ID of the product instance
      "<PRODUCT_A_INSTANCE_A>",
      // Unique ID of the product instance
      "<PRODUCT_A_INSTANCE_B>"
    ],
    "<PRODUCT_ID_B>": [
      // Unique ID of the product instance
      "<PRODUCT_B_INSTANCE_A>",
      // Unique ID of the product instance
      "<PRODUCT_B_INSTANCE_B>"
    ]
  }
}

API Response Caching

By default, API responses are cached for 24 hours. The first query will have a longer response time, but subsequent queries with the same parameters should have faster response times. A separate entry is cached for each unique tuple based on the following information:

  • organization identifier from the request token
  • input query parameters

Bypassing or Updating the Cached Response

If you have updated trace data within the previous 24 hours, you may want to retrieve the latest trace information. To bypass the cache, provide an HTTP header named X-ApiCache-Bypass with a value of true. This will bypass the API cache and return the latest available trace information.

Be aware that bypassing the cache will result in much longer response times, so only provide the header when there has been updated trace information. When the cache is bypassed, the latest response information will be added to the current API cache. Therefore, subsequent requests with the same parameters will return the updated trace information.

IBM Food Trust wiki

WELCOME!
  Modules
  Membership
  Languages
  Browsers

ONBOARDING
  Onboarding Steps
  Data Requirements
  Data Types
   Supplier Data
   Payload Data
   Insights Data

HOW-TO
  Join by Invitation
  Log in as New User
  Authenticate Human Users
  Authenticate System Users
   Java Sample
   Typescript Sample
   IIB Sample
  Assign User Roles
  Upload Data
  Automate Data Upload
  Convert Spreadsheets
  Convert Data
  Whitelist Custom URLs

APIs-Swagger
  Connector API
  Documents API
  Converter API
  Trace API
  Insights API

APIs-Usage
  APIs
  Insights API
  Insights API Usage
  Trace API
  Connector API Errors
  API Error Codes

REFERENCE
  GS1
  GS1 Identifier Reuse
  Authentication
  Identifiers
  Message Codes
  Cryptographic
   Signatures
  Signature Header
  Access Control
  Firewall Settings
  XML to JSON
   EPCIS Aggregation Add
   EPCIS Aggregation Delete
   EPCIS Object Add
   EPCIS Object Delete
   EPCIS Object Observed
   EPCIS Transformation
   Purchase Order
   Despatch Advice
   Receiving Advice
   Master Data Item
   Master Data Facility
   Standard Business
    Document Header

FAQ

SUPPORT PROCESS

Clone this wiki locally