APIs
This document describes how to register an application as an IBM Food Trust System User, and configure the application to submit credentials and upload data (assets) to the IBM Food Trust solution. Please refer to GDPR Section on ensuring that no personal data is uploaded to IBM Food Trust as free form text.
The IBM Food Trust APIs enable authenticated (and authorized) end users, including system users and applications, to upload data to the IBM Food Trust solution network. To successfully upload GS1 Asset XML to the IBM Food Trust solution, authenticated users must submit their credentials with each API call. Once the submitted data is validated and transformed by the solution, the assets are created on the network and available for transactions with other authorized users.
The diagram shown below (Figure 1) illustrates the overall flow of creating an application System ID and submitting data to IBM Food Trust through API calls:
Figure 1. IBM Food Trust system user authentication and API calls
The three steps shown above in Figure 1. are described in detail below:
- 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 Manage Users Dashboard, 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 call to the IBM Food Trust API Post Asset endpoint, to upload assets or to IBM Food Trust. Information about the created asset is returned to the application.
IBM Food Trust requires authentication to submit data to the system. Please see How To Get an Authentication Token for System Users for detailed information.
The IBM Food Trust Connector API described below writes data to blockchain. Successful invocation of this API sends an XML document to IBM Food Trust, which is then stored on blockchain.
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.
When submitting requests programmatically to IBM Food Trust APIs, set the User-Agent request header to a string with the 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
Call the Asset endpoint to submit an XML message to the IBM Food Trust solution in the required message format. For help generating XML messages using a spreadsheet, the Spreadsheet Converter tool is available.
The IBM Food Trust API endpoints are documented in Swagger:
| HTTP Method | Endpoint | Purpose |
|---|---|---|
| POST | /fs/connector/v1/assets |
Submits XML to Food Trust solution. |
For authentication, the caller'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)
|
- 201 Asset Created. This is returned when the submitted XML has been successfully processed. A response body will also be returned containing the asset ids that were generated for each asset contained in the xml.
Sample 201 Asset Created response body with asset ids
{
"message": {
"ids": [
"urn:ibm:provenance:asset:event:transformation:org:default:default:dbdadc0dc3b2d36d4028c1d8f24b090cea63c5017b1d272fd688d9189907e10e",
"urn:ibm:provenance:asset:object:lotILMD:org:default:default:95bc06fef9dd2a7081bdb795399b7d1c8f52dfc6630d095d2dda10620b421c4a",
"urn:ibm:provenance:asset:object:lotILMD:org:default:default:0d38c56f0886a5cd7ee69fd63030b170bbc0997a926e441ecba7296410db6335"
]
}
}
- Common error responses can be found here.