docs: enriched the EDR API overview with transfer documentation

eclipse-tractusx · Sep 6, 2023 · 67e5b9f · 67e5b9f
1 parent cc20afb
commit 67e5b9f
Show file tree

Hide file tree

Showing 2 changed files with 122 additions and 4 deletions.
diff --git a/docs/samples/edr-api-overview/edr-api-overview.md b/docs/samples/edr-api-overview/edr-api-overview.md
@@ -75,6 +75,37 @@ This endpoint will perform the contract negotiation, transfer process and EDR st
 }
 ```
 
+The EDR negotiation returns only the id of the negotiation process that has been started.
+
+The EDR negotiation rely on two steps, contract negotiation and transfer process, both of which are asynchronous.
+In order to plug-in and get notified in every state of the two state machines, callbacks can be configured while starting
+the EDR negotiation:
+
+```json
+{
+  ...
+  "callbackAddresses": [
+    {
+      "uri": "http://localhost:8080/hooks",
+      "events": [
+        "transfer.process.started"
+      ],
+      "transactional": false
+    }
+  ]
+}
+```
+
+In this case we are interested only when the transfer process transition to the `STARTED` state.
+
+Once the EDR has been negotiated with the provider, the EDR itself will be stored in the configured vault and the metadata
+associated to it in the configured datasource for future querying.
+
+Since `tractusx-edc` v0.5.1 the cached EDRs also come with a state machine that will manage the lifecycle of an EDR
+on the consumer side. That means that it will auto-renew itself when the expiration date is approaching by
+firing another transfer process request with the same parameters as the original one. Once renewed the old-one
+will transition to the state `EXPIRED` and it will be removed from the database and the vault according to the [configuration](../../../core/edr-core/README.md)
+
 ### EDR Management | Fetch cached EDRs
 
 This endpoint will retrieve all EDR entries by their `assetId` or `agreementId` references, which are passed as `query parameters`.
@@ -89,9 +120,12 @@ This endpoint will retrieve all EDR entries by their `assetId` or `agreementId`
 [
   {
     "@type": "tx:EndpointDataReferenceEntry",
-    "edc:agreementId": "contract-agreement-id",
-    "edc:transferProcessId": "transfer-process-id",
-    "edc:assetId": "asset-id",
+    "edc:agreementId": "MQ==:MQ==:NGU2MWRhMzQtNTUwOC00MDU1LThhZjUtYzZhODdlOTUxY2Ux",
+    "edc:transferProcessId": "3f79d8e0-830b-434b-ada2-d2c4c1271c8f",
+    "edc:assetId": "1",
+    "edc:providerId": "BPNL000000000001",
+    "tx:edrState": "NEGOTIATED",
+    "tx:expirationDate": 1693928132000,
     "@context": {
       "dct": "https://purl.org/dc/terms/",
       "tx": "https://w3id.org/tractusx/v0.0.1/ns/",
@@ -104,6 +138,8 @@ This endpoint will retrieve all EDR entries by their `assetId` or `agreementId`
 ]
 ```
 
+### EDR Management | Fetch single EDR
+
 This endpoint, through the `transfer-process-id` passed as `path variable`, will retrieve the actual EDR.
 
 | Path                                          | Method | Query Params             |
@@ -133,3 +169,85 @@ This endpoint, through the `transfer-process-id` passed as `path variable`, will
 ```
 
 > Please note that now with the EDR you are able to request the `Asset` data from provider's `data-plane`.
+
+### EDR Management | Deleting a cached EDR
+
+This endpoint will delete the EDR entry associated with the `transfer-process-id` and it will remove the EDR itself
+from the vault.
+
+| Path                                          | Method | Query Params             |
+|-----------------------------------------------|--------|--------------------------|
+| `<MANAGEMENT_URL>/edrs/{transfer-process-id}` | DELETE | none                     |
+
+### EDR Usage | Fetching data
+
+Once the EDR has been negotiated and stored, the data can be fetched in two ways depending on the use-case:
+
+- Provider data-plane (EDC way)
+- Consumer proxy (tractus-x EDC simplified)
+
+#### Provider data-plane
+
+Once the right EDR has been identified using the EDR management API the current asset/agreement/transfer-process that
+you want to transfer, we can use the `endpont`, `authCode` and `authKey` to make the request:
+
+```sh
+curl --request GET \
+  --url http://provider-data-plane/public-url \
+  --header 'Authorization: auth-code' \
+  --header 'Content-Type: application/json' 
+```
+
+If the HTTP asset exposed has been configured to proxy also query parameters and path segments they will be forwarded
+to the backend from the provider data-plane:
+
+```sh
+curl --request GET \
+  --url http://provider-data-plane/public-url/subroute?foo=bar \
+  --header 'Authorization: auth-code' \
+  --header 'Content-Type: application/json' 
+```
+
+#### Consumer data-plane (proxy)
+
+The Consumer data-plane proxy is an extension available in `tractusx-edc` that will use the EDR store to simplify
+the data request on consumer side. The documentation is available [here](../../../edc-extensions/dataplane-proxy/edc-dataplane-proxy-consumer-api/README.md).
+
+The only API is:
+
+| Path                      | Method | Query Params             |
+|---------------------------|--------|--------------------------|
+| `<PROXY_URL>/aas/request` | POST   | none                     |
+
+which fetches the data according to the input body. The body should contain the `assetId` plus `providerId` or the `transferProcessId`,
+which identifies the EDR to use for fetching data and an `endpointUrl` which is the [provider gateway](../../../edc-extensions/dataplane-proxy/edc-dataplane-proxy-provider-api/README.md)
+on which the data is available.
+
+Example:
+
+```sh
+curl --request POST \
+  --url http://localhost:8186/proxy/aas/request \
+  --header 'Content-Type: application/json' \
+  --header 'X-Api-Key: password' \
+  --data '{"assetId": "1","providerId": "BPNL000000000001","endpointUrl": "http://localhost:8080/api/gateway/aas/test"}'
+```
+
+Alternatively if the `endpointUrl` is not known or the gateway on the provider side is not configured, it can be omitted and the `Edr#endpointUrl`
+will be used as base url. In this scenario if needed, users can provide additional properties to the request for composing the final
+url:
+
+- `pathSegments` sub path to append to the base url
+- `queryParams` query parameters to add to the url
+
+Example of an asset with base url `http://localhost:8080/test`
+
+```sh
+curl --request POST \
+  --url http://localhost:8186/proxy/aas/request \
+  --header 'Content-Type: application/json' \
+  --header 'X-Api-Key: password' \
+  --data '{"assetId": "1","providerId": "BPNL000000000001","pathSegments": "/sub","queryParams": "foo=bar"}'
+```
+
+The final url will look like `http://localhost:8080/test/sub?foo=bar`.
diff --git a/edc-extensions/dataplane-proxy/edc-dataplane-proxy-consumer-api/README.md b/edc-extensions/dataplane-proxy/edc-dataplane-proxy-consumer-api/README.md
@@ -36,7 +36,7 @@ Example with base url `http://localhost:8080/test`
 
 The final url will look like `http://localhost:8080/test/sub?foo=bar` composed by the DataPlane manager with the Http request flow,
 
-> Note: the endpoint is not protected with configured `AuthenticationService`, which most likely will be the token based (auth key) one.
+> Note: the endpoint is protected with configured `AuthenticationService`.
 
 ## Configuration