APIs
The IBM Food Trust (IFT) Solution is the first step of the system. By submitting either GS1 asset xml, or certificate JSON information to the solution, it will then be validated and transformed into a format that will then be used to build relationships between assets.
The diagram shown below illustrates the overall flow of an application program that utilizes the IFT API.
- Before running an application program that uses the IFT API, a system ID must be created. Your organization administrator can creates a system ID using the Manage Users Dashboard and get and obtain a client ID and a secret for the system ID. These values need to be stored in the form that the application program can consume, for example, a configuration file or environment variables.
- Run the application program. It reads the system ID/client ID/secret and sends them to Authorization API to get access token.
- Once the access token is obtained, the application program invokes IFT API with the access token to send asset XML files or/and send certificate JSON files.
The Access Token endpoint is used to obtain an access token, which is a JSON Web Token (JWT) defined in RFC 7519.
The obtained token is used for sending to other IFT API endpoints with the Authorization header parameter for endpoint authentication.
Notes:
- The access token expires in three hours. If it is expired, IFT API returns 401 (User Unauthorized).
- A Java library is provided to get an access token without calling the endpoint diretly. See How do I obtain an authorization token? for more information.
| Host name |
|---|
| https://fs-identity-dev.mybluemix.net/ |
| HTTP Verb | Endpoint | Purpose |
|---|---|---|
| POST | /identity/v0/token |
Obtain an access token (JWT) |
| Header Parameter | Value |
|---|---|
| Content-Type | application/json |
| Accept | application/json |
Four parameters are sent to the endpoint as a JSON data in the payload. Three parameters out of four are created on the IFT Manage Users Dashboard.
| Property Name | Type | Description |
|---|---|---|
| username | string | System ID defined on the user management page. |
| password | string | Secret defined on the user management page. |
| grant_type | string | Grant type (password is the only value supported) |
| client_id | string | Client ID defined on the user management page. |
There are 3 main responses you will receive from this endpoint
| Response | Meaning |
|---|---|
| 200 | Access token created |
| 400 | Error in parameters |
| 401 | User Unauthorized |
When the endpoint successfully ended, the returned response contains following JSON data.
| Property Name | Description |
|---|---|
| id_token | Access token (JWT) |
| success | Response code (200) |
- 401: User Unauthorized. A user will receive a 401 response if there is a problem with the credentials (username/password/client_id) sent to the endpoint. Make sure the correct credentials for a System ID created using the Manage Users Dashboard
- 400: Bad Data. A user will receive a 400 response if there is a problem with data they uploaded. The response will give a detailed message of the problem.
NOTE: For compliance with data privacy laws, no data that personally identifies an individual, should be submitted to IFT system.
The Asset endpoint is used to send an IFT Message to the solution. The format for these message types can be found here. If you are new to the solution, we have a couple of helper tools that you can leverage to create the XML messages -- they are the XML Generator and the Excel Converter.
For more detailed information, as well as example files look at the swagger, which can be found at:
https://fs-connector.mybluemix.net/swagger-ui.html
| HTTP Verb | Endpoint | Purpose |
|---|---|---|
| POST | /fs/connector/v1/assets |
Send xml to the Food Trust System. |
An access token (JWT) has to be sent with the Authorization header parameter for authentication.
| Header Parameter | Value |
|---|---|
| Authorization |
Bearer + ' ' (a space character) + Access Token (JWT)
|
There are 3 main responses you will receive from this endpoint
| Response | Meaning |
|---|---|
| 201 | Asset Created |
| 400 | Error in xml |
| 401 | User Unauthorized |
- 401: User Unauthorized. A user will receive a 401 response if there is a problem with their authorization token. Typical cases are:
- missing Authorization header
- authorization token has expired (it has been more than three (3) hours since the authorization token was issued)
- the user sent the incorrect token for the zone they're working in (integration/production)
- 400: Bad Data. A user will receive a 400 response if there is a problem with data they uploaded. The response will give a detailed message of the problem.
A list of common errors can be found here
The certificate endpoint is used to send an IFT Certificate Message to the solution. The format for this message type can be found here
| HTTP Verb | Endpoint | Purpose |
|---|---|---|
| POST | /fs/connector/v1/assets/certificates |
Send a certificate JSON to the IBM Food Trust system |
| Header Parameter | Value |
|---|---|
| Authorization | Bearer (token) |
There are 3 main responses you will receive from this endpoint
| Response | Meaning |
|---|---|
| 201 | Asset Created |
| 400 | Error in JSON |
| 401 | User Unauthorized |
- 401: User Unauthorized. A user will receive a 401 response if there is a problem with their authorization token. Typical cases are:
- missing Authorization header
- authorization token has expired (it has been more than three (3) hours since the authorization token was issued)
- the user sent the incorrect token for the zone they're working in (integration/production)
- 400: Bad Data. A user will receive a 400 response if there is a problem with data they uploaded. The response will give a detailed message of the problem.
A list of common errors can be found here