Following endpoint is used as utility endpoint, logic behind it is hiding logic related with IDS message creation. This endpoint is not password protected. Body of the request is json, with key-pair structure. Possible keys, with some predefined values are:
multipart, of type String, with predefined values: mixed, form, http-header, wss; required
forwardTo of type String, should be formatted as URI; required
messageType - of type String, messages that are currently supported/logic implemented; required
forwardToInternal of type String, should be formatted as URI; used in case of wss flow
payload - of type String, json object; can be left out
requestedArtifact - of type String, should be formatted as URI
requestedElement - of type String, should be formatted as URI
transferContract - of type String, should be formatted as URI\
This endpoint is used to initiate flow, as convenient method, so that we do not need to take care of creating properly formatted IDS message. It will be used in other test cases as a starting request.
In case of wrong value for multipart parameter, following error response will be returned
Missing proper value for MULTIPART, should be one of: 'mixed', 'form', 'http-header'
In case of missing multipart parameter:
Multipart field not found in request, mandatory for the flow
In case of not supported message - messageType parameter:
{
"timestamp": "2023-02-21T15:05:36.678+0000",
"status": 500,
"error": "Internal Server Error",
"message": "No message available",
"path": "/proxy"
}
/data endpoint
Endpoint exposed by the Connector, used to receive requests from other Connectors in Dataspace.
Depending of the connector configuration, data received on this endpoint will be processes accordingly (mixed/form/header) and validate IDS message.
Regarding example requests, feel free to use same requests, for configuration, like described in internal endpoints
/about/version
Main purpose for this endpoint is to provide version of the deployed Execution Core Container version. This endpoint is not password protected.
User can also use it to check if TRUE Connector is ready for use (if component is completed with initialization/startup).
Following set of endpoints are used to manipulate with Self Description document, like get, add, update or remove specific element. All of the endpoints are password protected, and require user with ADMIN role.
/api/contractOffer/
Used to perform CRUD operations over contractOffer element of Self Description.
GET contract offer
Required header element - contractOffer of type URI
If header element is not present or if contract offer does not exist, following response is returned:
{
"message": "Missing request header 'contractOffer' for method parameter of type URI"
}
or
{
"message": "Did not find contract offer with id 'https://w3id.org/idsa/autogen/textResource/424e2559-50ad-411e-bea0-93ff6550aa80'"
}
POST contract offer
Add new contract offer to offered resource.
Required parameters are:
resource - of type String, should be formatted as URI contractOffer - of type String, json representation of de.fraunhofer.iais.eis.ContractOfferImpl class
NOTE: It is required to provide context in json representation, otherwise, request data will not be parsed correct and subelements will not be created properly, which might result in invalid data added to Self Description.
If everything is correct, as response, updated self description will be returned, with HTTP status 200, and user can verify that response contains newly added contract offer.
In case of invalid input data (ContractOffer json string), HTTP status code 400, with following error will be returned:
{
"message": "Error while processing request\nCould not transform input to an appropriate implementing class for de.fraunhofer.iais.eis.ContractOffer"
}
If contract offer already exists, HTTP status code 400, with following error response will be returned:
{
"message": "Contract offer with id 'https://w3id.org/idsa/autogen/contractOffer/1dbb4896-7222-4c9d-8789-c58727a30884' already exists"
}
In case of invalid resource id - HTTP status code 404:
{
"message": "Resource with id 'https://w3id.org/idsa/autogen/textResource/a329a2fd-1002-4753-822e-89561f148838' not found"
}
PUT contract offer
Update existing contract offer.
Required parameters are:
resource - of type String, should be formatted as URI contractOffer - of type String, json representation of de.fraunhofer.iais.eis.ContractOfferImpl class
Successful scenario will return in response updated self description, with HTTP status 200, and user can verify that response contains updated contract offer.
In case of failed update, use case is the same like with adding contract offer - invalid input data or contract offer with such id does not exists or resource with id does not exists.
DELETE contract offer
Removes contract offer from self description document.
Required header element - contractOffer of type URI
In case of non existing offered resource, HTTP status 404:
{
"message": "Resource with id 'https://w3id.org/idsa/autogen/textResource/6e7c04f2-a09d-41b2-8334-013877bbda13' not found"
}
When resource header is not present, HTTP status 500:
{
"message": "Missing request header 'resource' for method parameter of type URI"
}
POST offered resource
Add new offered resource to catalog.
Required parameters are:
catalog - of type String, should be formatted as URI resource - of type String, json representation of de.fraunhofer.iais.eis.ResourceImpl class
NOTE: It is required to provide context in json representation, otherwise, request data will not be parsed correct and subelements will not be created properly, which might result in invalid data added to Self Description.
If everything is correct, as response, updated self description will be returned, with HTTP status 200, and user can verify that response contains newly added offered resource.
In case of invalid input data (Resource json string), HTTP status code 400, with following error will be returned:
{
"message": "Error while processing request\nCould not transform input to an appropriate implementing class for de.fraunhofer.iais.eis.Resource"
}
If contract resource exists, HTTP status code 400, with following error response will be returned:
{
"message": "Resource with id 'https://w3id.org/idsa/autogen/textResource/6e7c04f2-test-41b2-8334-013877bbda12' already exists"
}
In case of invalid resource id - HTTP status code 404:
{
"message": "Resource with id 'https://w3id.org/idsa/autogen/textResource/6e7c04f2-test-41b2-8334-013877bbda12' not found"
}
If catalog header parameter is missing or invalid, proper error response message will be sent back
{
"message": "Missing request header 'catalog' for method parameter of type URI"
}
or
{
"message": "Did not find resourceCatalog with id https://w3id.org/idsa/autogen/resourceCatalog/c65c6d5d-ffdd-4872-a8ee-cc0aa6e223f9"
}
PUT offered resource
Update existing offered resource.
Required parameters are:
catalog - of type String, should be formatted as URI resource - of type String, json representation of de.fraunhofer.iais.eis.ResourceImpl class
Successful scenario will return in response updated self description, with HTTP status 200, and user can verify that response contains updated resource offer.
In case of failed update, use case is the same like with adding offered resource - invalid input data or offered resource with such id does not exists or catalog with id does not exists.
DELETE
Removes offered resource from Self Description document
{
"message": "Missing request header 'representation' for method parameter of type URI"
}
or
{
"message": "Did not find representation with id 'https://w3id.org/idsa/autogen/textRepresentation/09b9b628-77ee-40a2-98c4-79b559370cdb'"
}
POST representation
Add new representation to offered resource.
Required parameters are:
resource - of type String, should be formatted as URI representation - of type String, json representation of de.fraunhofer.iais.eis.RepresentationImpl class
NOTE: It is required to provide context in json representation, otherwise, request data will not be parsed correct and sub-elements will not be created properly, which might result in invalid data added to Self Description.
If everything is correct, as response, updated self description will be returned, with HTTP status 200, and user can verify that response contains newly added representation.
In case of invalid input data (Representation json string), HTTP status code 400, with following error will be returned:
{
"message": "Error while processing request\nCould not transform input to an appropriate implementing class for de.fraunhofer.iais.eis.Representation"
}
If contract offer already exists, HTTP status code 400, with following error response will be returned:
{
"message": "Representation with id 'https://w3id.org/idsa/autogen/textRepresentation/09b9b628-test-40a2-98c4-79b559370cda' already exists"
}
In case of invalid resource id - HTTP status code 404:
{
"message": "Resource with id 'https://w3id.org/idsa/autogen/textResource/a329a2fd-1002-4753-822e-89561f148838' not found"
}
PUT representation
Update existing representation.
Required parameters are:
resource - of type String, should be formatted as URI representation - of type String, json representation of de.fraunhofer.iais.eis.RepresentationImpl class
Successful scenario will return in response updated self description, with HTTP status 200, and user can verify that response contains updated representation.
In case of failed update, use case is the same like with adding representation - invalid input data or representation with such id does not exists or resource with id does not exists.
DELETE representation
Removes representation from self description document.
Required header element - representation of type URI
In case password check is not successful, response message will contain information, which user can inspect and correct new password.
Internal endpoints
Endpoint used to receive proxy request from DataApp. DataApp, will after receiving proxy request, creates valid IDS message request, and send it to Execution Core Container.
This request is a bit specific, since it is required to convert IDS message to http headers (logic that DataApp proxy request do for you) and when conversion is done correct this is how request looks like, depending of the Messagetype and its mandatory fields:
If any of the mandatory headers is not present or that message cannot be recreated from headers, response will be returned and user should check header responses, for IDS-Messagetype = ids:RejectionMessage and IDS-RejectionReason = https://w3id.org/idsa/code/MALFORMED_MESSAGE.
Broker
There are convenient endpoints to initiate flow with Broker. They can be triggered from proxy endpoint. In order to do that, messageType in the proxy request must be correct. All of those endpoints will create valid IDS message and send message to connector, which will add IDS related elements (DAPS token and other) and forward to Broker. In order to send message to the Broker, Forward-To parameter of proxy request must have Broker URL. If Broker requires authentication, please set correct credentials in request, TRUE Connector will forward authorization header to destination, without modifying it.
Processing of the response will be done based of the Broker response.
/selfRegistration/register
Message type of the proxy request - ConnectorUpdateMessage
/selfRegistration/update
Message type of the proxy request - ConnectorUpdateMessage
/selfRegistration/delete
Message type of the proxy request - ConnectorUnavailableMessage
/selfRegistration/passivate
Message type of the proxy request - ConnectorUnavailableMessage
/selfRegistration/query
Message type of the proxy request - QueryMessage
WSS
Flow starts when API receives start frame, and ends when end frame is received. Data in between are buffered, and once whole package is received, it will try to recreate multipart/mixed request and continue with processing received request. Logic applies for both endpoints listed below.
Data received are binary packets.
timerEndpointA
Interface between Consumer DataApp and Connector, to support receiving request data in WebSocket flow.
timerEndpointB
Interface between 2 connectors.
Logic regarding recreating request is same like for timerEndpointA
