diff --git a/docs/developer/Technical-Documentation/requests/example-requests.md b/docs/developer/Technical-Documentation/requests/example-requests.md new file mode 100644 index 00000000..b40485a9 --- /dev/null +++ b/docs/developer/Technical-Documentation/requests/example-requests.md @@ -0,0 +1,228 @@ +# Example Requests + +The policy hub provides 4 endpoints. All endpoints are readonly endpoints although one of them is a post endpoint. + +## GET: Policy Attributes + +The endpoint is accessible under `/api/policy-hub/policy-attributes` and can be used to receive all possible attribute types. + +## GET: Policy Types + +The endpoint is accessible under `/api/policy-hub/policy-types`. It can be used to receive all available policies with all their attributes. + +It's possible to filter the results by one of the following or both attributes: + +- Type + - Access + - Usage + - Purpose +- UseCase + - Traceability + - Quality + - PCF + - Behavioraltwin + - Sustainability + +As an result you'll receive a list of policies: + +```json +[ + { + "technicalKey": "BusinessPartnerNumber", + "type": [ + "Access", + "Usage" + ], + "description": "The business partner number restriction can get used to define which exact business partners (based on BPNL) are allowed to view or negotiate the respective data offer. Please ensure that you add minimum one 16-digit BPNL Number in the rightOperand; wildcards are not supported.", + "useCase": [ + "Traceability", + "Quality", + "PCF", + "Behavioraltwin", + "Sustainability" + ], + "attribute": [ + { + "key": "Regex", + "value": "^BPNL[\\w|\\d]{12}$" + } + ], + "technicalEnforced": true + }, + { + "technicalKey": "Membership", + "type": [ + "Access", + "Usage" + ], + "description": "The membership credential can get used to ensure that only CX members are allowed to view or negotiate the respective data offer.", + "useCase": [ + "Traceability", + "Quality", + "PCF", + "Behavioraltwin", + "Sustainability" + ], + "attribute": [ + { + "key": "Static", + "value": "active" + } + ], + "technicalEnforced": true + }, + { + "technicalKey": "FrameworkAgreement.traceability", + "type": [ + "Usage" + ], + "description": "With the Framework Credential, only those participants which have signed the respective framework agreement (general or via a specific version) are allowed to view or negotiate the respective data offer. Generic: \"rightOperand\": \"active\"; specific \"rightOperand\": \"active:{version}\"", + "useCase": [ + "Traceability" + ], + "attribute": [ + { + "key": "Version", + "value": "1.0" + }, + { + "key": "Version", + "value": "1.1" + }, + { + "key": "Version", + "value": "1.2" + } + ], + "technicalEnforced": true + } +] +``` + +## GET PolicyContent + +The endpoint is accessible under `/api/policy-hub/policy-content?useCase={useCase}&type={type}&credential={technicalKey}&operatorId={operator}&value={value}` and can be used to receive a concrete json file for a policy. + +The parameter you need to set for this endpoint can be received from the [policy-types](#get-policy-types) endpoint. The useCase as well as value are optional parameters. If you try to receive the content for a policy which has the Regex Attribute a value needs to be passed which is matching the regex pattern. + +A possible response can look like this: + +```json +{ + "content": { + "@context": [ + "https://www.w3.org/ns/odrl.jsonld", + { + "cx": "https://w3id.org/catenax/v0.0.1/ns/" + } + ], + "@type": "Offer", + "@id": "....", + "permission": { + "action": "use", + "constraint": { + "leftOperand": "FrameworkAgreement.traceability", + "operator": "eq", + "rightOperand": "@FrameworkAgreement.traceability-Version" + } + } + }, + "attributes": [ + { + "key": "@FrameworkAgreement.traceability-Version", + "possibleValues": [ + "active:1.0", + "active:1.1", + "active:1.2" + ] + } + ] +} +``` + +As you can see the policy content was requested with operatorId = Equals, since the FrameworkAgreement.traceability has multiple values the values of the rightOperand will be displayed in an attributes array with the respective key used to link the values. + +## POST: Policy Content + +The endpoint is accessible under `/api/policy-hub/policy-content` and can be used to receive a concrete json file for a policy with and / or linked constraints. + +The body of the request needs to contain the policyType and constraintOperand, valid values for the contraintOperand are `And` or `Or`. + +The constrains can be passed as an array, the content of the array is a combination of the technicalKey of a policy type and the operator either `Equals` or `In`. + +Limitations: the technicalKey of a constraint must only be included once. + +And example: + +```json +{ + "policyType": "Usage", + "constraintOperand": "And", + "constraints": [ + { + "key": "FrameworkAgreement.traceability", + "operator": "Equals" + }, + { + "key": "companyRole.dismantler", + "operator": "In" + } + ] +} + +``` + +Or example: + +```json +{ + "PolicyType": "Usage", + "ConstraintOperand": "Or", + "Constraints": [ + { + "Key": "FrameworkAgreement.traceability", + "Operator": "Equals" + }, + { + "Key": "companyRole.dismantler", + "Operator": "In" + } + ] +} + +``` + +Multiple constrains example: + +```json +{ + "PolicyType": "Usage", + "ConstraintOperand": "And", + "Constraints": [ + { + "Key": "FrameworkAgreement.traceability", + "Operator": "Equals" + }, + { + "Key": "companyRole.dismantler", + "Operator": "In" + }, + { + "Key": "BusinessPartnerNumber", + "Operator": "Equals", + "Value": "BPNL00000003CRHK" + } + ] +} + +``` + +If you want to try it out, check the [postman collection](/docs/developer/Technical-Documentation/requests/policy-hub.postman_collection.json) + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/policy-hub diff --git a/docs/developer/Technical-Documentation/requests/policy-hub.postman_collection.json b/docs/developer/Technical-Documentation/requests/policy-hub.postman_collection.json new file mode 100644 index 00000000..eceb5e21 --- /dev/null +++ b/docs/developer/Technical-Documentation/requests/policy-hub.postman_collection.json @@ -0,0 +1,646 @@ +{ + "info": { + "_postman_id": "664c9cb3-c8fc-433f-bbdc-912bd2122052", + "name": "Policy Hub", + "description": "Hey there 👋\n\nthis collection gives you an overview of the policy hub api and some example requests.\n\nTo use the collection please set a environment variable called `baseUrl` with the url you want to test, e.g. [https://localhost:5001](https://localhost:5001) to test locally or https://policy-hub.dev.demo.catena-x.net\n\nto test the policy hub on dev.\n\nTo be able to test the api you need a valid token from the respective keycloak instance. Set the keyloak token within a variable called `hubToken`", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", + "_exporter_id": "2223943" + }, + "item": [ + { + "name": "Get PolicyTypes", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-types", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-types" + ] + } + }, + "response": [ + { + "name": "Get PolicyTypes With Type Filter", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-types?type=Access", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-types" + ], + "query": [ + { + "key": "type", + "value": "Access" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get PolicyTypes With UseCase Filter", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-types?useCase=Traceability", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-types" + ], + "query": [ + { + "key": "useCase", + "value": "Traceability" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + } + ] + }, + { + "name": "Get PolicyContent", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?type=Usage&credential=FrameworkAgreement.traceability&operatorId=Equals", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "useCase", + "value": "Traceability", + "disabled": true + }, + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "FrameworkAgreement.traceability" + }, + { + "key": "operatorId", + "value": "Equals" + } + ] + } + }, + "response": [ + { + "name": "Get Membership Content", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?type=Usage&credential=Membership&operatorId=Equals", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "Membership" + }, + { + "key": "operatorId", + "value": "Equals" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get BPN Content", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?type=Usage&credential=BusinessPartnerNumber&operatorId=Equals&value=BPNL00000003CRHK", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "BusinessPartnerNumber" + }, + { + "key": "operatorId", + "value": "Equals" + }, + { + "key": "value", + "value": "BPNL00000003CRHK" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get Framework Content", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?type=Usage&credential=FrameworkAgreement.traceability&operatorId=Equals", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "useCase", + "value": "Traceability", + "disabled": true + }, + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "FrameworkAgreement.traceability" + }, + { + "key": "operatorId", + "value": "Equals" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get Dismantler Content", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?type=Usage&credential=companyRole.dismantler&operatorId=In", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "companyRole.dismantler" + }, + { + "key": "operatorId", + "value": "In" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get Purpose TraceBattery", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?useCase=Traceability&type=Usage&credential=purpose.trace.v1.TraceBattery&operatorId=Equals", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "useCase", + "value": "Traceability" + }, + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "purpose.trace.v1.TraceBattery" + }, + { + "key": "operatorId", + "value": "Equals" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get Purpose Trace Aspects", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?useCase=Traceability&type=Usage&credential=purpose.trace.v1.aspects&operatorId=Equals", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "useCase", + "value": "Traceability" + }, + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "purpose.trace.v1.aspects" + }, + { + "key": "operatorId", + "value": "Equals" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get Purpose QualityAnalysis", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?useCase=Traceability&type=Usage&credential=purpose.trace.v1.qualityanalysis&operatorId=Equals", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "useCase", + "value": "Traceability" + }, + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "purpose.trace.v1.qualityanalysis" + }, + { + "key": "operatorId", + "value": "Equals" + } + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get PolicyContent", + "originalRequest": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content?type=Usage&credential=companyRole.dismantler&operatorId=In", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ], + "query": [ + { + "key": "type", + "value": "Usage" + }, + { + "key": "credential", + "value": "companyRole.dismantler" + }, + { + "key": "operatorId", + "value": "In" + } + ] + } + }, + "status": "OK", + "code": 200, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json; charset=utf-8" + }, + { + "key": "Date", + "value": "Tue, 14 Nov 2023 21:53:59 GMT" + }, + { + "key": "Server", + "value": "Kestrel" + }, + { + "key": "Transfer-Encoding", + "value": "chunked" + } + ], + "cookie": [], + "body": "{\n \"content\": {\n \"@context\": [\n \"https://www.w3.org/ns/odrl.jsonld\",\n {\n \"cx\": \"https://w3id.org/catenax/v0.0.1/ns/\"\n }\n ],\n \"@type\": \"Offer\",\n \"@id\": \"....\",\n \"permission\": {\n \"action\": \"use\",\n \"constraint\": {\n \"leftOperand\": \"Dismantler.activityType\",\n \"operator\": \"in\",\n \"rightOperand\": [\n \"Audi\",\n \"BMW\",\n \"VW\"\n ]\n }\n }\n }\n}" + } + ] + }, + { + "name": "Get PolicyContent", + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\r\n \"PolicyType\": \"Usage\",\r\n \"ConstraintOperand\": \"And\",\r\n \"Constraints\": [\r\n {\r\n \"Key\": \"FrameworkAgreement.traceability\",\r\n \"Operator\": \"Equals\"\r\n },\r\n {\r\n \"Key\": \"companyRole.dismantler\",\r\n \"Operator\": \"In\"\r\n }\r\n ]\r\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ] + } + }, + "response": [ + { + "name": "Get Content with AND", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n \"PolicyType\": \"Usage\",\r\n \"ConstraintOperand\": \"And\",\r\n \"Constraints\": [\r\n {\r\n \"Key\": \"FrameworkAgreement.traceability\",\r\n \"Operator\": \"Equals\"\r\n },\r\n {\r\n \"Key\": \"companyRole.dismantler\",\r\n \"Operator\": \"In\"\r\n }\r\n ]\r\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get with multiple constraints", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n \"PolicyType\": \"Usage\",\r\n \"ConstraintOperand\": \"And\",\r\n \"Constraints\": [\r\n {\r\n \"Key\": \"FrameworkAgreement.traceability\",\r\n \"Operator\": \"Equals\"\r\n },\r\n {\r\n \"Key\": \"companyRole.dismantler\",\r\n \"Operator\": \"In\"\r\n },\r\n {\r\n \"Key\": \"BusinessPartnerNumber\",\r\n \"Operator\": \"Equals\",\r\n \"Value\": \"BPNL00000003CRHK\"\r\n }\r\n ]\r\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Get Content with OR", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n \"PolicyType\": \"Usage\",\r\n \"ConstraintOperand\": \"Or\",\r\n \"Constraints\": [\r\n {\r\n \"Key\": \"FrameworkAgreement.traceability\",\r\n \"Operator\": \"Equals\"\r\n },\r\n {\r\n \"Key\": \"companyRole.dismantler\",\r\n \"Operator\": \"In\"\r\n }\r\n ]\r\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-content", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-content" + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + } + ] + }, + { + "name": "Get Attributes", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/policy-hub/policy-attributes", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "policy-hub", + "policy-attributes" + ] + } + }, + "response": [] + } + ], + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{hubToken}}", + "type": "string" + } + ] + }, + "event": [ + { + "listen": "prerequest", + "script": { + "type": "text/javascript", + "exec": [ + "" + ] + } + }, + { + "listen": "test", + "script": { + "type": "text/javascript", + "exec": [ + "" + ] + } + } + ] +} \ No newline at end of file