Trace API

Trace API Usage

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

API Documentation

Trace API Documentation (April 2019) PDF

Swagger

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

• Sandbox Outbound API Swagger
• Production Outbound API Swagger

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.

Abbreviated Trace EPCs

EPCs may be encountered more than once in a Trace API call return. In order to reduce the return size, duplicate EPCs are marked as "abbreviated" and only one is expanded. In the following examples, EPC urn:ibm:ift:lpn:obj:2500765432158.001147 appears twice in the trace. The first is expanded while the duplicate is abbreviated.

Example of expanded EPC:

  "parent_epcs": [
    {
      "epc_id": "urn:ibm:ift:lpn:obj:2500765432158.001147",
      "events": [
        {
          "asset_id": "urn:ibm:provenance:asset:event:aggregation:6784449c-9dd1-4c81-9523-265da0fae04e:default:test.e2e_595e92ae-dfc6-4354-b339-fe3bd63bdd7d:9f48cee1e1e5f00ec4667b023c340aa86e93e500640fb6e8bc5ec646a616d890"
        },
        {
          "asset_id": "urn:ibm:provenance:asset:event:disaggregation:56cbcc5a-a55e-4f70-bf6d-a40d2a9bf4bf:default:test.e2e_595e92ae-dfc6-4354-b339-fe3bd63bdd7d:0268e04bd15792c9e28adaf4c517434730d43524098d21b890294821a5c3c83d"
        }
      ],
      "output_epcs": [],
      "input_epcs": [],
      "parent_epcs": []
    }

Example of abbreviated duplicate EPC:

  "parent_epcs": [
    {
      "epc_id": "urn:ibm:ift:lpn:obj:2500765432158.001147",
      "events": [],
      "output_epcs": [],
      "input_epcs": [],
      "parent_epcs": [],
      "abbreviated": true
    }

Depth

Depth is a zero-based index for the number of recursive queries required to build a trace. The initial query (depth 0) looks for all events where the traced EPC ID exists as a parent, child, input, or output. The returned asset IDs and EPC IDs are inserted into the trace at the first level. The next query (depth 1) then takes all returned EPC IDs from the previous query and searches for them as parents, children, inputs, and outputs. These asset IDs and EPC IDs are inserted into the trace at the next level. This process continues until either the depth is reached or there is no more data returned by the query.

The Trace API has a default depth of 5, and there is no upper limit on the depth value that can be specified. However, if a trace exceeds 500,000 contained EPC IDs, an error is returned and a lower depth should be specified on the next request. The EPC (epc_id) endpoints have a depth of 5, which cannot be changed.

A trace level may consist of any of these events:

1. The transformation from one EPC to another (inputs to outputs)
2. One or more child EPCs being aggregated into a parent
3. One parent being disaggregated into one or more children EPCs