diff --git a/.gitignore b/.gitignore index 73b46dafa..db38f6a58 100644 --- a/.gitignore +++ b/.gitignore @@ -20,7 +20,6 @@ # SPDX-License-Identifier: Apache-2.0 ################################################################################## -__pycache__/ .DS_Store node_modules dist @@ -67,3 +66,82 @@ tgz ## Backup Files *.bck *.bak + +######## Python - inspired by https://github.com/github/gitignore/blob/main/Python.gitignore + +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST +*.manifest +*.spec +pip-log.txt +pip-delete-this-directory.txt +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ +*.mo +*.pot +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal +instance/ +.webassets-cache +.scrapy +docs/_build/ +.pybuilder/ +target/ +.ipynb_checkpoints +profile_default/ +ipython_config.py +.pdm.toml +__pypackages__/ +celerybeat-schedule +celerybeat.pid +*.sage.py +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ +.spyderproject +.spyproject +.ropeproject +/site +.mypy_cache/ +.dmypy.json +dmypy.json +.pyre/ +.pytype/ +cython_debug/ \ No newline at end of file diff --git a/dpp-backend/digitalproductpass/README.md b/dpp-backend/digitalproductpass/README.md new file mode 100644 index 000000000..4c2fa9e39 --- /dev/null +++ b/dpp-backend/digitalproductpass/README.md @@ -0,0 +1,385 @@ + + +

  Digital Product Pass Backend

+ + +

Version: v2.0.1

+ +
+ +# Table of contents + +- [Table of contents](#table-of-contents) +- [What is this backend app responsible for?](#what-is-this-backend-app-responsible-for) +- [Services Available](#services-available) + - [Authentication Services](#authentication-services) +- [Open API specification](#open-api-specification) + - [Digital Product Pass APIs](#digital-product-pass-apis) + - [Parameters](#parameters) + - [/api/contract/create](#apicontractcreate) + - [/api/contract/search](#apicontractsearch) + - [/api/contract/agree](#apicontractagree) + - [/api/contract/decline](#apicontractdecline) + - [/api/contract/cancel](#apicontractcancel) + - [/api/contract/status/{processId}](#apicontractstatusprocessid) + - [/api/data](#apidata) +- [Detailed API Services](#detailed-api-services) + - [/api/data](#apidata-1) + - [Request body](#request-body) + - [Contract API](#contract-api) + - [/api/contract/create](#apicontractcreate-1) + - [Request body](#request-body-1) + - [/api/contract/search](#apicontractsearch-1) + - [Request body](#request-body-2) + - [/api/contract/agree](#apicontractagree-1) + - [Request body](#request-body-3) + - [/api/contract/decline](#apicontractdecline-1) + - [Request body](#request-body-4) + - [/api/contract/cancel](#apicontractcancel-1) + - [Request body](#request-body-5) + - [/api/contract/status/](#apicontractstatus) + - [IRS API](#irs-api) + - [Request parameters](#request-parameters) + - [Public API](#public-api) + - [Response](#response) +- [OSS License Check](#oss-license-check) +- [Swagger Docs](#swagger-docs) +- [Run the application](#run-the-application) + - [Modify the configurations in the deployment files](#modify-the-configurations-in-the-deployment-files) +- [TL;DR](#tldr) + - [Install](#install) +- [License](#license) + + +# What is this backend app responsible for? + +This backend includes the services and *logics* to manage the *passports* of the `frontend app`. + +# Services Available + +## Authentication Services +All Authenticated APIs required a `AccessToken` JWT Token generated by the login in the frontend or in the Catena-X Keycloak instance. + +```yaml +{ + headers: { + Authorization: "Bearer <>" + } +} +``` + +For login and log out! +```bash +------ +/auth/check #With this api you can check you authentication status. +------ +/auth/token #Request token from the keycloak instance +------ +/auth/userInfo #With this api you can get your user information. +------ +``` + + +# Open API specification + +The Digital Product Pass Open API specification is available at the swagger hub from Tractus-X: + +[https://app.swaggerhub.com/apis/eclipse-tractusx-bot/digital-product-pass](https://app.swaggerhub.com/apis/eclipse-tractusx-bot/digital-product-pass) + +## Digital Product Pass APIs +The APIs below are the ones contain in the `Digital Product Pass Backend` reference implementation. Which can be reused for retrieving aspects from the Catena-X Network. + + | API | Method | Description | Parameters | + | ------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | **/api/contract/create** | POST | The `/api/contract/create` api is responsible for calling the `BPN Discovery` service searching for the BPN of a `manufacturerPartId` and validating if there is any `Decentral Digital Twin Registry` available for the BPN number found in the `EDC Discovery` service. | [Go to Params](#apicontractcreate) + | **/api/contract/search** | POST | At the **/api/contract/search** API the user can search for a serialized Id and get its contract. The `Backend` will search for the Digital Twin and will return the contract for the first one that is found. A `sign token` (a sha256 hash) is return also and acts like a "session token" allowing just the user that created the process to sign or decline the contract. |[Go to Params](#apicontractsearch) | + | **/api/contract/agree** | POST | Once the user has the contract he can call the `/api/contract/agree` API to start the negotiation process and the transfer of the passport. This means that the user accepted the policy and the frame-contracts contained in the contract policy. | [Go to Params](#apicontractagree) | + | **/api/contract/decline** | POST | The other option rather than `/agree` is the `/decline` API, that basically blocks the process and makes it invalid. This means that the user declined the specific contract that was found for this process. | [Go to Params](#apicontractdecline) + | **/api/contract/cancel** | POST | The user can use `/cancel` to interrupt the negotiation process once it is signed by mistake if is the case. It will be only valid until the negotiation is made. | [Go to Params](#apicontractcancel) + | **/api/contract/status/``** | GET | After the user signs the contract he can use the `/status` API to get the process status and see when it is ready to retrieve the passport using the API `/data`.. | [Go to Params](#apicontractstatusprocessid) + | **/api/data** | POST | The API `/data` will decrypt the passport file that is encrypted using the session token "sign token", and will delete the file so that it is returned just once to the user and can not be accessed anymore. So a new passport will be always need to be requested.. | [Go to Params](#apidata) | + + +### Parameters + +#### /api/contract/create + +| Parameter | Value Name | Mandatory or Optional Value | +|-----------|------------------|-----------------------------| +| id | searchIdValue | [REQUIRED] | +| type | searchIdTypeName | manufacturerPartId | + + +#### /api/contract/search + +| Parameter | Value Name | Mandatory or Optional Value | +|-----------|-----------------------|-----------------------------| +| id | serializedIdValue | [REQUIRED] | +| idType | serializedIdTypeName | partInstanceId | +| processId | processIdentification | [REQUIRED] | + + + #### /api/contract/agree + +| Parameter | Value Name | Mandatory or Optional Value | +|------------|------------------------|---------------------------------------------------------------------------------| +| processId | processIdentification | [REQUIRED] | +| contractId | contractIdentification | [REQUIRED] | +| policyId | policyIdentification | If no policyId is specified then the first policy of the contract will be taken | +| token | searchSessionToken | [REQUIRED] | + +#### /api/contract/decline + +| Parameter | Value Name | Mandatory or Optional Value | +|------------|------------------------|-----------------------------| +| processId | processIdentification | [REQUIRED] | +| token | searchSessionToken | [REQUIRED] | + + +#### /api/contract/cancel + +| Parameter | Value Name | Mandatory or Optional Value | +|------------|------------------------|-----------------------------| +| processId | processIdentification | [REQUIRED] | +| contractId | contractIdentification | [REQUIRED] | +| token | searchSessionToken | [REQUIRED] | + + +#### /api/contract/status/{processId} +| Parameter | Value Name | Mandatory or Optional Value | +|-----------|-----------------------|-----------------------------| +| processId | processIdentification | [REQUIRED] | + + +#### /api/data + +| Parameter | Value Name | Mandatory or Optional Value | +|------------|------------------------|-----------------------------| +| processId | processIdentification | [REQUIRED] | +| contractId | contractIdentification | [REQUIRED] | +| token | searchSessionToken | [REQUIRED] | + + +# Detailed API Services +> **_NOTE:_** You must be authenticated with the keycloak instance to access this APIs + + +### /api/data +Get data from a Catena-X Provider by using its processId, contractId and a token, this retrieves product passport after a successful negotiation. + +```bash +/api/data #Returns the data negotiated and transferred +``` +###### Request body +```json +{ + "processId": "string", + "contractId": "string", + "token": "string", + "policyId": "optional:string" +} +``` + +### Contract API + +#### /api/contract/create + +```bash +/api/contract/create #Creates a process and checks for the viability of the data retrieval +``` +###### Request body +```json +{ + "id": "string", + "type": "string" +} +``` + +#### /api/contract/search + +```bash +/api/contract/search #Searches for a passport with the following id +``` +###### Request body +```json +{ + "processId": "string", + "id": "string", + "children": true // Optional Boolean + "idType": "optional:string", + "dtIndex": 0, //Optional Integer + "idShort": "optional:string" +} +``` + +#### /api/contract/agree + +```bash +/api/contract/agree #Sign contract retrieved from provider and start negotiation +``` +###### Request body +```json +{ + "processId": "string", + "contractId": "string", + "token": "string", + "policyId": "optional:string" +} +``` + +#### /api/contract/decline + +```bash +/api/contract/decline #Decline passport negotiation +``` +###### Request body +```json +{ + "processId": "string", + "token": "string" +} +``` +#### /api/contract/cancel + +```bash +/api/contract/cancel #Cancel the negotiation +``` +###### Request body +```json +{ + "processId": "string", + "contractId": "string", + "token": "string", + "policyId": "optional:string" +} +``` + +#### /api/contract/status/ + +```bash +/api/contract/status/ #Get status from process +``` + +## IRS API + +```bash +/api/irs// #Endpoint called by the IRS to set status completed +``` +###### Request parameters +``` +- Id +- State +``` +```bash +/api/irs//tree #Api called by the frontend to obtain the tree of components +``` +```bash +/api/irs//state #Api called by the frontend to check if the process is finished +``` +```bash +/api/irs//components #Api called by the frontend to obtain the list of components of the tree +``` + +## Public API + +Public APIs don't require authentication +```bash +/health #Get the health status of the server +``` +###### Response +```json +{ + "message": "RUNNING", + "status": 200, + "data": "24/11/2022 17:48:18.487" +} +``` + +```bash +/endpoint/ #Receives the EDR from the EDC Consumer and get the passport json +``` + +```bash +/endpoint// #Receives the EDR for the EDC Consumer and queries for the dDTR +``` + + + +# OSS License Check + +The third party library dependecies, utilized in this app have to be approved from The Eclipse Foundation. + +The [Dash Licence Tool](https://github.com/eclipse/dash-licenses) is used to scan the dependencies + +[OSS License Checks with Dash & Compliance with Apache 2.0](https://confluence.catena-x.net/pages/viewpage.action?pageId=54989501) + +At the time of writing this manual, the dependencies have status approved and therefore no need to generate IP Team Review request further. + +[Maven plugin](https://github.com/eclipse/dash-licenses/blob/master/README.md#maven-plugin-options) used to check OSS license + +How to run: +```bash +mvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.summary=DEPENDENCIES +``` + + +# Swagger Docs + +Swagger documentation is now automatically available at the following path: + +```https:///swagger-ui/index.html``` + +![img.png](docs/media/img2.png) + +For authorization, you will need to add a JWT Access token from the Catena-X IAM: + +![img3.png](docs/media/img3.png) + +# Run the application + +Use maven to run the spring boot application: +```bash +mvn spring-boot:run +``` + +If you want to run the application in a different way checkout the [frequently asked questions](#frequently-asked-questions) section below. + +## Modify the configurations in the deployment files + +You can use the default configuration to start the application: +```charts/digital-product-pass/values.yaml``` + +However if you need to change it just create a new environment with this naming convention: ```values-env`.yaml``` where ```env``` is the name of your environment. You can use as an example the following configuration file: ```charts/digital-product-pass/values-int.yaml```. + +The configuration for the consumer backend application is a yaml file that is configured in the following tag: ```backend.application```. Before the application starts all the configuration parameters must be specified, since they are required for initialization and will be checked at the test fase. + +Once you configured the application use the follow the [TL;DR](#tldr) below to ```build the image and start the application``` using helm charts. + +# TL;DR + +## Install +Find more documentation on how to install the backend in the [INSTALL.md](../../INSTALL.md) file. + +# License +[Apache-2.0](https://raw.githubusercontent.com/catenax-ng/product-battery-passport-consumer-app/main/LICENSE) diff --git a/dpp-backend/scripts/README.md b/dpp-backend/scripts/README.md index 4e8547aa0..2ef9a63bd 100644 --- a/dpp-backend/scripts/README.md +++ b/dpp-backend/scripts/README.md @@ -1,7 +1,8 @@