To facilitate IBM Food Trust™ data uploads, you can register an application as an IBM Food Trust system user and configure the application to submit credentials and upload XML data (products, facilities, events, and transactions).
Attention: To comply with EU General Data Protection Regulation (GDPR) data privacy requirements, you must ensure that no personal data is uploaded to IBM Food Trust in any free-form text fields or in any comments.
IBM Food Trust APIs enable authenticated, authorized users, including human users, system users, and applications, to upload data to the network. To successfully upload asset XML, authenticated users must submit their credentials with each API call. Once the data is validated and accepted by IBM Food Trust, the assets are available for sharing with your selected IBM Food Trust business partners.
Figure 1 and the steps that follow illustrate the flow of creating an IBM Food Trust system ID for an application and submitting data to IBM Food Trust through API calls:
Figure 1. IBM Food Trust system user authentication and API calls
The three steps in Figure 1 are detailed as follows:
- To call an IBM Food Trust API, the application (system user) must have a registered system ID. An organization administrator must create the system ID using the Users module and manually record the generated system ID, client ID, and secret (password) for the application. These credentials must then be stored in a form that is consumable by the application—as a configuration file or environment variables, for example.
- The application submits its system ID, client ID and secret in a call to the authorization API access token endpoint. If successful, the API returns an access token (JSON web token/JWT) to the application.
- The application submits its received access token (JWT) in a POST call to the IBM Food Trust API Asset endpoint, to upload assets to IBM Food Trust. Information about the created asset is returned to the application.
IBM Food Trust allows only authenticated users to upload data. To authenticate applications, refer to the authenticate system users documentation.
The IBM Food Trust Connector API enables authenticated users to upload data to IBM Food Trust.
User-Agent request header
When submitting requests programmatically to IBM Food Trust APIs, set the User-Agent request header to a string with your organization name. Optionally, the program name and version can be added to the string.
Example using organization name:
Example using organization name, program name, and program version:
Post Asset XML
The Connector API endpoints are provided in Swagger:
||Submits XML to IBM Food Trust|
For authentication, the registered user's access token JWT must be submitted in the
Authorization header of the POST request:
One of three responses is typically returned by this endpoint:
|400||Error in XML|
401: User Unauthorized. A 401 response indicates a problem with the credentials (username/password/client_id) submitted to the endpoint. Ensure that the correct credentials for a system ID created using the Users module are submitted.
400: Bad Data. A 400 response indicates a problem with the uploaded data. The response includes a detailed description of the problem.
For additional information, refer to API error messages.