docs(asset): Add documentation of asset creation on new management API #361

saschaisele-zf · 2023-05-17T01:24:37Z

WHAT

Adds a documentation with examples for the new management API.

WHY

With extensive changes to the API and the migration to a new protocol, both the requests and the terminology change significantly.
This documentation aims to alleviate the confusion.

…of assets on the new management api Signed-off-by: Sascha Isele <[email protected]>

added values table to asset creation, started with terminology entries and expanded assets examples to asset entry examples Signed-off-by: Sascha Isele <[email protected]>

docs/samples/Create Asset.md

Signed-off-by: Sascha Isele <[email protected]>

docs/samples/Create Asset.md

…amples Signed-off-by: Sascha Isele <[email protected]>

Signed-off-by: Sascha Isele <[email protected]>

additionally adjusted the examples lean more towards real use-cases Signed-off-by: Sascha Isele <[email protected]>

saschaisele-zf · 2023-05-17T16:27:23Z

Still needs some work but it should be enough for a proper review now.
@paullatzelsperger , @ndr-brt , @florianrusch-zf

sonarqubecloud · 2023-05-17T16:32:19Z

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

florianrusch-zf · 2023-05-19T06:11:45Z

docs/samples/Create Asset.md

+
+## 1. Optional - Local Setup
+
+TODO link to a 0.4.x example setup.


When will this be available?

florianrusch-zf · 2023-05-19T06:14:42Z

docs/samples/Create Asset.md

+
+## 2. Terminology
+
+With the migration to a new protocol and with it new specifications, DCAT Catalogs in the context of assets, there is a need to clarify the terminology that is used.


Additionally, can we provide links to the new protocol and the specification?

Suggested change

With the migration to a new protocol and with it new specifications, DCAT Catalogs in the context of assets, there is a need to clarify the terminology that is used.

With the migration to the new protocol and with its new specification, DCAT Catalogs in the context of assets, there is a need to clarify the terminology that is used.

florianrusch-zf · 2023-05-19T06:16:24Z

docs/samples/Create Asset.md

+| Key      | Description                                                                                                                          |
+|----------|--------------------------------------------------------------------------------------------------------------------------------------|
+| @context | JSON-LD context aims to enable the local usage of compact and meaningful names which are later still identifiable in a larger scope. |
+| @vocab   | The value of `@vocab` is added as prefix to any key consisting of a plain string without any other prefix.                           |
+| edc      | `edc` defines a specific prefix for the connector.                                                                                   |
+| @id      | `@id` contains a distinct identifier enabling global references to this field, also called a Node.                                   |
+| @type    | Specifies the path to the schema which describes this Node.                                                                          |


Suggested change

| Key | Description |

|----------|--------------------------------------------------------------------------------------------------------------------------------------|

| @context | JSON-LD context aims to enable the local usage of compact and meaningful names which are later still identifiable in a larger scope. |

| @vocab | The value of `@vocab` is added as prefix to any key consisting of a plain string without any other prefix. |

| edc | `edc` defines a specific prefix for the connector. |

| @id | `@id` contains a distinct identifier enabling global references to this field, also called a Node. |

| @type | Specifies the path to the schema which describes this Node. |

| Key | Description |

|------------|--------------------------------------------------------------------------------------------------------------------------------------|

| `@context` | JSON-LD context aims to enable the local usage of compact and meaningful names which are later still identifiable in a larger scope. |

| `@vocab` | The value of `@vocab` is added as prefix to any key consisting of a plain string without any other prefix. |

| `edc` | `edc` defines a specific prefix for the connector. |

| `@id` | `@id` contains a distinct identifier enabling global references to this field, also called a Node. |

| `@type` | Specifies the path to the schema which describes this Node. |

florianrusch-zf · 2023-05-19T06:21:59Z

docs/samples/Create Asset.md

+| @context | JSON-LD context aims to enable the local usage of compact and meaningful names which are later still identifiable in a larger scope. |
+| @vocab   | The value of `@vocab` is added as prefix to any key consisting of a plain string without any other prefix.                           |
+| edc      | `edc` defines a specific prefix for the connector.                                                                                   |
+| @id      | `@id` contains a distinct identifier enabling global references to this field, also called a Node.                                   |


field or object?

florianrusch-zf · 2023-05-19T06:22:23Z

docs/samples/Create Asset.md

+|----------|--------------------------------------------------------------------------------------------------------------------------------------|
+| @context | JSON-LD context aims to enable the local usage of compact and meaningful names which are later still identifiable in a larger scope. |
+| @vocab   | The value of `@vocab` is added as prefix to any key consisting of a plain string without any other prefix.                           |
+| edc      | `edc` defines a specific prefix for the connector.                                                                                   |


Whats the purpose of this prefix?

florianrusch-zf · 2023-05-19T06:22:54Z

docs/samples/Create Asset.md

+| Key      | Description                                                                                                                          |
+|----------|--------------------------------------------------------------------------------------------------------------------------------------|
+| @context | JSON-LD context aims to enable the local usage of compact and meaningful names which are later still identifiable in a larger scope. |
+| @vocab   | The value of `@vocab` is added as prefix to any key consisting of a plain string without any other prefix.                           |


Whats the purpose of this?

florianrusch-zf · 2023-05-19T06:25:11Z

docs/samples/Create Asset.md

+  "edc:dataAddress": {
+    "@type": "edc:dataAddress",
+    "type": "test-type",
+    "keyName": "test-key-name"


In my opinion using a real type of dataAddress would be more beneficial. E.g. HttpData

florianrusch-zf · 2023-05-19T06:27:18Z

docs/samples/Create Asset.md

+
+The asset entry is then sent to the management API of the connector through a POST request.
+
+**CON_DATAMGMT_URL** specifies the URL of the management API.


Suggested change

**CON_DATAMGMT_URL** specifies the URL of the management API.

**CON_DATAMGMT_URL** specifies the base URL of the connector context, where the management API is available.

florianrusch-zf · 2023-05-19T06:32:27Z

docs/samples/Create Asset.md

+      "edc:version": "0.2.1",
+      "contenttype": "application/json"
+    },
+    "edc:privateProperties": {


why do we have here the edc prefix and on the "normale" properties not?

Is it, because the edc stores everything which is prefixed with edc: separately?

florianrusch-zf · 2023-05-19T06:34:57Z

docs/samples/Create Asset.md

+An example is the `payload` field and its contents.
+Here the `payload` contains the name and age of a person.


Can it be anything? Because then I wouldn't use the term payload. This sounds like, that I can store the to be transmitted data within this field.

ndr-brt · 2023-05-22T07:01:41Z

docs/samples/Create Asset.md

+    "edc": "https://w3id.org/edc/v0.0.1/ns/"
+  },
+  "edc:asset": {
+    "@type": "edc:asset",


Suggested change

"@type": "edc:asset",

"@type": "Asset",

ndr-brt · 2023-05-22T07:04:52Z

docs/samples/Create Asset.md

+    "@id": "some-asset-id"
+  },
+  "edc:dataAddress": {
+    "@type": "edc:dataAddress",


Suggested change

"@type": "edc:dataAddress",

"@type": "DataAddress",

ndr-brt · 2023-05-22T07:05:41Z

docs/samples/Create Asset.md

+
+The asset entry is then sent to the management API of the connector through a POST request.
+
+**CON_DATAMGMT_URL** specifies the URL of the management API.


Suggested change

**CON_DATAMGMT_URL** specifies the URL of the management API.

**MANAGEMENT_URL** specifies the URL of the management API.

ndr-brt · 2023-05-22T07:05:58Z

docs/samples/Create Asset.md

+The asset entry is then sent to the management API of the connector through a POST request.
+
+**CON_DATAMGMT_URL** specifies the URL of the management API.
+The path `/management/v2` allows access to the functionality of the new management API.


Suggested change

The path `/management/v2` allows access to the functionality of the new management API.

The path `/v2` allows access to the functionality of the new management API.

ndr-brt · 2023-05-22T07:06:41Z

docs/samples/Create Asset.md

+> Once that is done, the new management API can be reached through `/management`.
+
+```bash
+curl -X POST "${CON_DATAMGMT_URL}/management/v2/assets" \


Suggested change

curl -X POST "${CON_DATAMGMT_URL}/management/v2/assets" \

curl -X POST "${MANAGEMENT_URL}/v2/assets" \

as /management should be already part of the MANAGEMENT_URL (and, in fact, it is configurable)

ndr-brt · 2023-05-22T07:08:41Z

docs/samples/Create Asset.md

+    "properties": {
+      "name": "some-asset-name",
+      "description": "some description",
+      "edc:version": "0.2.1",


please either namespace all the properties of none of them, unless we'd want/need to add tractusx specific properties, that could be namespaced accordingly

saschaisele-zf added 2 commits May 17, 2023 01:40

docs(asset): added outline and examples for documenting the creation …

e3090ec

…of assets on the new management api Signed-off-by: Sascha Isele <[email protected]>

docs(asset): better examples for asset creation

1a71e1f

added values table to asset creation, started with terminology entries and expanded assets examples to asset entry examples Signed-off-by: Sascha Isele <[email protected]>

florianrusch-zf reviewed May 17, 2023

View reviewed changes

docs/samples/Create Asset.md Outdated Show resolved Hide resolved

ndr-brt self-requested a review May 17, 2023 06:12

ndr-brt reviewed May 17, 2023

View reviewed changes

docs/samples/Create Asset.md Outdated Show resolved Hide resolved

docs(asset): linting and incorporated first reviews

a2655f6

Signed-off-by: Sascha Isele <[email protected]>

saschaisele-zf changed the title ~~feat(docs): add Documentation of asset creation on new management API~~ docs(asset): add Documentation of asset creation on new management API May 17, 2023

saschaisele-zf changed the title ~~docs(asset): add Documentation of asset creation on new management API~~ docs(asset): Add documentation of asset creation on new management API May 17, 2023

docs(asset): added first descriptions

a29630d

Signed-off-by: Sascha Isele <[email protected]>

florianrusch-zf requested changes May 17, 2023

View reviewed changes

saschaisele-zf added 4 commits May 17, 2023 15:53

docs(asset): another review, finished descriptions and streamlined ex…

96ef6e6

…amples Signed-off-by: Sascha Isele <[email protected]>

docs(asset): fixed some typos

382ef2b

Signed-off-by: Sascha Isele <[email protected]>

docs(asset): added bash commands to all examples

5790d6d

Signed-off-by: Sascha Isele <[email protected]>

docs(asset): added an explanation for JSON-LD specific values

7f7d648

additionally adjusted the examples lean more towards real use-cases Signed-off-by: Sascha Isele <[email protected]>

saschaisele-zf marked this pull request as ready for review May 17, 2023 16:27

saschaisele-zf requested review from ndr-brt and florianrusch-zf May 17, 2023 16:27

florianrusch-zf requested changes May 19, 2023

View reviewed changes

ndr-brt reviewed May 22, 2023

View reviewed changes

florianrusch-zf mentioned this pull request May 31, 2023

Docs/0 4 0 migration guide #430

Closed

saschaisele-zf closed this Jun 1, 2023

saschaisele-zf deleted the docs/management_api/create_asset branch July 14, 2023 12:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(asset): Add documentation of asset creation on new management API #361

docs(asset): Add documentation of asset creation on new management API #361

saschaisele-zf commented May 17, 2023

saschaisele-zf commented May 17, 2023

sonarqubecloud bot commented May 17, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

florianrusch-zf May 19, 2023

ndr-brt May 22, 2023

ndr-brt May 22, 2023

ndr-brt May 22, 2023

ndr-brt May 22, 2023

ndr-brt May 22, 2023

ndr-brt May 22, 2023


		## 1. Optional - Local Setup

		TODO link to a 0.4.x example setup.


		## 2. Terminology

		With the migration to a new protocol and with it new specifications, DCAT Catalogs in the context of assets, there is a need to clarify the terminology that is used.

	With the migration to a new protocol and with it new specifications, DCAT Catalogs in the context of assets, there is a need to clarify the terminology that is used.
	With the migration to the new protocol and with its new specification, DCAT Catalogs in the context of assets, there is a need to clarify the terminology that is used.


		The asset entry is then sent to the management API of the connector through a POST request.

		CON_DATAMGMT_URL specifies the URL of the management API.

	CON_DATAMGMT_URL specifies the URL of the management API.
	CON_DATAMGMT_URL specifies the base URL of the connector context, where the management API is available.

		An example is the `payload` field and its contents.
		Here the `payload` contains the name and age of a person.

	CON_DATAMGMT_URL specifies the URL of the management API.
	MANAGEMENT_URL specifies the URL of the management API.

	The path `/management/v2` allows access to the functionality of the new management API.
	The path `/v2` allows access to the functionality of the new management API.

	curl -X POST "${CON_DATAMGMT_URL}/management/v2/assets" \
	curl -X POST "${MANAGEMENT_URL}/v2/assets" \

docs(asset): Add documentation of asset creation on new management API #361

docs(asset): Add documentation of asset creation on new management API #361

Conversation

saschaisele-zf commented May 17, 2023

WHAT

WHY

saschaisele-zf commented May 17, 2023

sonarqubecloud bot commented May 17, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment