Skip to content
Wuchieh J. Jong edited this page Mar 1, 2019 · 18 revisions

IBM Food Trust™ APIs - uploading data

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

Summary

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 and Certificate JSON 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 and certificates 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

IBM Food Trust API Overview

The three steps shown above in Figure 1. are described in detail below:

  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 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.
  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 call to the IBM Food Trust API Post Asset or Post Certificate endpoint, to upload assets or certificates to IBM Food Trust. Information about the created asset or certificate is returned to the application.

Authentication

IBM Food Trust requires an authentication to submit data to the system. Please see How To Get an Authentication Token for System Users for detailed information.

IBM Food Trust API

GDPR

The IBM Food Trust API documented below is the only API that a customer can access that writes data to the Blockchain. The invocation of this API sends an XML document to Food Trust which is then stored on blockchain.

Users must ensure that no personal data is contained in any free text fields in the submitted XML document, or in any comments.

User-Agent request header

When submitting requests programatically to IBM Food Trust APIs, it is recommended that the User-Agent request header is set 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

Post Asset XML

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.

Swagger

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)

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 Manage Users Dashboard, 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 error messages, refer to IBM Food Trust Solution Errors.


Post Certificate JSON

Call the Certificate endpoint to send certificate JSON to the IBM Food Trust solution in the required message format

Swagger

The IBM Food Trust Certificate API endpoint is documented in Swagger:

HTTP Verb Endpoint Purpose
POST /fs/connector/v1/assets/certificates Sends certificate JSON to IBM Food Trust
Header Parameter Value
Authorization Bearer (token)

Responses

One of three responses is typically returned by the Certificate endpoint:

Response Meaning
201 Asset Created
400 Error in JSON
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 Manage Users Dashboard, were 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 error messages, refer to IBM Food Trust Solution Errors.

IBM Food Trust wiki

WELCOME!
    Modules
    Membership
    Updates

ONBOARDING
    Onboarding Steps
    Data Requirements
       Data Types
       Supplier Data
       Test Data

HOW-TO
    Authenticate Human Users
    Authenticate System Users
       Java Code Sample        Typescript Code Sample        IBM Integration Bus (IIB)     Assign User Roles
    Upload Data
    Automate Data Upload
    Convert Spreadsheets
    Convert Data
    Manage Certificates

APIs
    Connector API
    Converter API
    Certificates API
    API Error Codes

REFERENCE
    GS1
    Authentication
    Identifiers
    Message Codes
    Cryptographic Signatures
    Signature Header
    Access Control
    Firewall Settings

FAQ

GET SUPPORT

DEPRECATED TOOLS
    XML Generator
    XML Validator

Clone this wiki locally
You can’t perform that action at this time.