Upload evidence through API

Edit online

You can upload evidence files Concert for internal reference and tracking using the API.

Draft comment: erin.pelkey@ibm.com
I reduced and simplified the short description until we have clarity on what type of "evidence" we support today and can explain why someone would need to do this. This is basic info that we need to explain clearly. Otherwise, the user has no way of knowing what this mechanism is or how to use it.
Note: Refer to the https://developer.ibm.com/apis/catalog/concert--ibm-concert-api for a full index of endpoints and requests.

Before you begin

  • You must have Admin or Editor access to the application or environment for which you are uploading the evidence.
  • You must have a valid API key that is created from the Concert UI. Refer to Generating an API key for instructions.
  • Refer to API reference and authentication for more details about using the Concert API, including required headers and variables.
Draft comment: erin.pelkey@ibm.com
We other guidance can we provide here to help the user prepare for uploading evidence files? For example, what type of evidence do we accept and in what format(s)?

Request URL

https://${concert_host}:{port}/ingestion/api/v1/table_of_contents/el/upload_evidence

Code snippet

curl --request POST \
  --url https://${concert_host}:{port}/ingestion/api/v1/table_of_contents/el/upload_evidence \
  --header 'Authorization: {Bearer} $API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --header 'InstanceId: 0000-0000-0000-0000' \
  --header 'accept: application/json' \
  --form data_type=<data_type> \
  --form 'metadata=<metadata> \
  --form evidencefile=@<filepath>

Request body parameters

This table describes the parameters accepted in the request body.

Request body parameters
Parameter Description
data_type Custom data type. Accepts any user-defined string value
evidencefile The name of the file uploaded. Precede the file path with an @ symbol. For example: @slacksim-definition.json. The input file type can be in any format.

Metadata object

The metadata object contains an array of name/value pairs containing details about the evidence being provided.

Draft comment: erin.pelkey@ibm.com
I realize this is meant to be flexible, but can we at least describe what the example represents? What is this demonstrating evidence of?
[
  { "name": "usecase", "value": "application_360" },
  { "name": "event_time", "value": "2024-07-21T11:32:28Z" },
  { "name": "is_event_interesting", "value": "false" },
  { "name": "application_name", "value": "bravoapp" },
  { "name": "environment_name", "value": "qa" }
]
Note: You must specify an application or environment in the metadata object, otherwise you will receive an ENTITYNOTFOUND error.

Example request

curl --request POST \
  --url https://${concert_host}:{port}/ingestion/api/v1/table_of_contents/upload_evidence \
  --header 'Authorization: <type> <API_key)' \
  --header 'Content-Type: multipart/form-data' \
  --header 'InstanceId: 0000-0000-0000-0000' \
  --header 'accept: application/json' \
  --form data_type=package_sbom \
  --form 'metadata={"usecase": "application_360","event_time": "2024-07-21T11:32:28Z","is_event_interesting": false,"metadata": [{"name": "application_name","value": "bravoapp"}, { "name": "environment_name", "value": "qa"}]}' \
  --form evidencefile=@application-definition.json

Response codes

  • 201 Success. The file was uploaded successfully.
  • 400 Invalid request parameters. Please review your request.
  • 401 Unauthorized: Invalid token provided.
  • 403 Forbidden: You don't have permission to access this resource.
  • 500 Internal Server Error - An error occurred on the server.