Skip to content

Configure applications

Configure applications

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).

GDPR notice

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.

Summary

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 IBM Food Trust API overview

The three steps in Figure 1 are detailed as follows:

  1. 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.
  2. 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.
  3. 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.

Authentication

IBM Food Trust allows only authenticated users to upload data. To authenticate applications, refer to the authenticate system users documentation.

Connector API

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:

User-Agent: organizationName

Example using organization name, program name, and program version:

User-Agent: organizationName-ProgramName/1.0

Post Asset XML

Call the Assets endpoint to submit an XML message to IBM Food Trust in the required format. For help generating XML messages in the correct format, the Spreadsheet converter tool is available.

Swagger

The Connector API endpoints are provided in Swagger:

HTTP Method Endpoint Purpose
POST /fs/connector/v1/assets 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:

Header Parameter Value
Authorization Bearer + ' ' (a space character) + Access Token (JWT)

Responses

One of three responses is typically returned by this endpoint:

Response Meaning
201 Asset Created
400 Error in XML
401 User Unauthorized

Error responses

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.