docs: add example to asset management api (#3270)

eclipse-edc · Jul 5, 2023 · a96918e · a96918e
1 parent c9f8568
commit a96918e
Show file tree

Hide file tree

Showing 19 changed files with 470 additions and 172 deletions.
diff --git a/...e/src/test/java/org/eclipse/edc/connector/catalog/DatasetResolverImplPerformanceTest.java b/...e/src/test/java/org/eclipse/edc/connector/catalog/DatasetResolverImplPerformanceTest.java
diff --git a/...in/java/org/eclipse/edc/connector/api/management/asset/model/AssetCreationRequestDto.java b/...in/java/org/eclipse/edc/connector/api/management/asset/model/AssetCreationRequestDto.java
@@ -24,6 +24,7 @@
 import static org.eclipse.edc.jsonld.spi.JsonLdKeywords.ID;
 
 @JsonDeserialize(builder = AssetCreationRequestDto.Builder.class)
+@Deprecated(since = "0.1.3")
 public class AssetCreationRequestDto extends AssetRequestDto {
 
     @JsonProperty(value = ID)

diff --git a/...api/src/main/java/org/eclipse/edc/connector/api/management/asset/model/AssetEntryDto.java b/...api/src/main/java/org/eclipse/edc/connector/api/management/asset/model/AssetEntryDto.java
@@ -20,6 +20,7 @@
 import org.eclipse.edc.api.model.DataAddressDto;
 
 @JsonDeserialize(builder = AssetEntryDto.Builder.class)
+@Deprecated(since = "0.1.3")
 public class AssetEntryDto {
     private AssetCreationRequestDto asset;
     private DataAddressDto dataAddress;

diff --git a/.../src/main/java/org/eclipse/edc/connector/api/management/asset/model/AssetEntryNewDto.java b/.../src/main/java/org/eclipse/edc/connector/api/management/asset/model/AssetEntryNewDto.java
@@ -23,6 +23,7 @@
 import static org.eclipse.edc.spi.CoreConstants.EDC_NAMESPACE;
 
 @JsonDeserialize(builder = AssetEntryNewDto.Builder.class)
+@Deprecated(since = "0.1.3")
 public class AssetEntryNewDto {
 
     public static final String EDC_ASSET_ENTRY_DTO_TYPE = EDC_NAMESPACE + "AssetEntryDto";

diff --git a/...i/src/main/java/org/eclipse/edc/connector/api/management/asset/model/AssetRequestDto.java b/...i/src/main/java/org/eclipse/edc/connector/api/management/asset/model/AssetRequestDto.java
@@ -19,7 +19,7 @@
 import java.util.HashMap;
 import java.util.Map;
 
-
+@Deprecated(since = "0.1.3")
 public abstract class AssetRequestDto extends BaseDto {
 
     protected Map<String, Object> properties;

diff --git a/.../src/main/java/org/eclipse/edc/connector/api/management/asset/model/AssetResponseDto.java b/.../src/main/java/org/eclipse/edc/connector/api/management/asset/model/AssetResponseDto.java
@@ -22,6 +22,7 @@
 import java.util.Map;
 
 @JsonDeserialize(builder = AssetResponseDto.Builder.class)
+@Deprecated(since = "0.1.3")
 public class AssetResponseDto extends BaseResponseDto {
 
     private Map<String, Object> properties;

diff --git a/...main/java/org/eclipse/edc/connector/api/management/asset/model/AssetUpdateRequestDto.java b/...main/java/org/eclipse/edc/connector/api/management/asset/model/AssetUpdateRequestDto.java
@@ -21,6 +21,7 @@
 import java.util.Map;
 
 @JsonDeserialize(builder = AssetUpdateRequestDto.Builder.class)
+@Deprecated(since = "0.1.3")
 public class AssetUpdateRequestDto extends AssetRequestDto {
 
 

diff --git a/...va/org/eclipse/edc/connector/api/management/asset/model/AssetUpdateRequestWrapperDto.java b/...va/org/eclipse/edc/connector/api/management/asset/model/AssetUpdateRequestWrapperDto.java
@@ -14,6 +14,7 @@
 
 package org.eclipse.edc.connector.api.management.asset.model;
 
+@Deprecated(since = "0.1.3")
 public class AssetUpdateRequestWrapperDto {
 
     private AssetUpdateRequestDto requestDto;

diff --git a/...i/asset-api/src/main/java/org/eclipse/edc/connector/api/management/asset/v2/AssetApi.java b/...i/asset-api/src/main/java/org/eclipse/edc/connector/api/management/asset/v2/AssetApi.java
@@ -36,7 +36,7 @@
 @OpenAPIDefinition(info = @Info(description = "This contains both the current and the new Asset API, which accepts JSON-LD and will become the standard API once the Dataspace Protocol is stable. " +
         "The new Asset API is prefixed with /v2, and the old endpoints have been deprecated. At that time of switching, the old API will be removed, and this API will be available without the /v2 prefix.", title = "Asset API"))
 @Tag(name = "Asset")
-@Deprecated
+@Deprecated(since = "0.1.3")
 public interface AssetApi {
 
     @Operation(description = "Creates a new asset together with a data address",

diff --git a/...i/src/main/java/org/eclipse/edc/connector/api/management/asset/v2/AssetApiController.java b/...i/src/main/java/org/eclipse/edc/connector/api/management/asset/v2/AssetApiController.java
@@ -52,7 +52,7 @@
 @Consumes(APPLICATION_JSON)
 @Produces(APPLICATION_JSON)
 @Path("/v2/assets")
-@Deprecated
+@Deprecated(since = "0.1.3")
 public class AssetApiController implements AssetApi {
     private final TypeTransformerRegistry transformerRegistry;
     private final AssetService service;
@@ -72,6 +72,7 @@ public AssetApiController(AssetService service, DataAddressResolver dataAddressR
     @POST
     @Override
     public JsonObject createAsset(JsonObject assetEntryDto) {
+        logDeprecationWarning();
         validator.validate(EDC_ASSET_ENTRY_DTO_TYPE, assetEntryDto).orElseThrow(ValidationFailureException::new);
 
         var assetEntry = transformerRegistry.transform(assetEntryDto, AssetEntryNewDto.class)
@@ -92,6 +93,7 @@ public JsonObject createAsset(JsonObject assetEntryDto) {
     @Path("/request")
     @Override
     public JsonArray requestAssets(JsonObject querySpecDto) {
+        logDeprecationWarning();
         QuerySpec querySpec;
         if (querySpecDto == null) {
             querySpec = QuerySpec.Builder.newInstance().build();
@@ -117,6 +119,7 @@ public JsonArray requestAssets(JsonObject querySpecDto) {
     @Path("{id}")
     @Override
     public JsonObject getAsset(@PathParam("id") String id) {
+        logDeprecationWarning();
         var asset = of(id)
                 .map(it -> service.findById(id))
                 .orElseThrow(() -> new ObjectNotFoundException(Asset.class, id));
@@ -130,12 +133,14 @@ public JsonObject getAsset(@PathParam("id") String id) {
     @Path("{id}")
     @Override
     public void removeAsset(@PathParam("id") String id) {
+        logDeprecationWarning();
         service.delete(id).orElseThrow(exceptionMapper(Asset.class, id));
     }
 
     @PUT
     @Override
     public void updateAsset(JsonObject assetJsonObject) {
+        logDeprecationWarning();
         // validation removed because now the asset validation requires the dataAddress field
         // validator.validate(EDC_ASSET_TYPE, assetJsonObject).orElseThrow(ValidationFailureException::new);
 
@@ -150,6 +155,7 @@ public void updateAsset(JsonObject assetJsonObject) {
     @Path("{assetId}/dataaddress")
     @Override
     public void updateDataAddress(@PathParam("assetId") String assetId, JsonObject dataAddressJson) {
+        logDeprecationWarning();
         validator.validate(EDC_DATA_ADDRESS_TYPE, dataAddressJson).orElseThrow(ValidationFailureException::new);
 
         var dataAddressResult = transformerRegistry.transform(dataAddressJson, DataAddress.class)
@@ -163,6 +169,7 @@ public void updateDataAddress(@PathParam("assetId") String assetId, JsonObject d
     @Path("{id}/dataaddress")
     @Override
     public JsonObject getAssetDataAddress(@PathParam("id") String id) {
+        logDeprecationWarning();
         return of(id)
                 .map(it -> dataAddressResolver.resolveForAsset(id))
                 .map(it -> transformerRegistry.transform(it, JsonObject.class))
@@ -171,4 +178,8 @@ public JsonObject getAssetDataAddress(@PathParam("id") String id) {
                 .orElseThrow(() -> new ObjectNotFoundException(Asset.class, id));
     }
 
+    private void logDeprecationWarning() {
+        monitor.warning("the /v2/assets endpoint have been deprecated, please switch to the new /v3/assets");
+    }
+
 }
diff --git a/...i/asset-api/src/main/java/org/eclipse/edc/connector/api/management/asset/v3/AssetApi.java b/...i/asset-api/src/main/java/org/eclipse/edc/connector/api/management/asset/v3/AssetApi.java
@@ -25,23 +25,26 @@
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.json.JsonArray;
 import jakarta.json.JsonObject;
-import org.eclipse.edc.api.model.IdResponseDto;
-import org.eclipse.edc.api.model.QuerySpecDto;
-import org.eclipse.edc.connector.api.management.asset.model.AssetResponseDto;
-import org.eclipse.edc.connector.api.management.asset.model.AssetUpdateRequestDto;
-import org.eclipse.edc.spi.types.domain.asset.Asset;
+import org.eclipse.edc.api.model.ApiCoreSchema;
+import org.eclipse.edc.spi.types.domain.DataAddress;
 import org.eclipse.edc.web.spi.ApiErrorDetail;
 
+import java.util.Map;
+
+import static org.eclipse.edc.jsonld.spi.JsonLdKeywords.ID;
+import static org.eclipse.edc.jsonld.spi.JsonLdKeywords.TYPE;
+import static org.eclipse.edc.spi.types.domain.asset.Asset.EDC_ASSET_TYPE;
+
 @OpenAPIDefinition(info = @Info(description = "This contains both the current and the new Asset API, which accepts JSON-LD and will become the standard API once the Dataspace Protocol is stable. " +
         "The new Asset API is prefixed with /v2, and the old endpoints have been deprecated. At that time of switching, the old API will be removed, and this API will be available without the /v2 prefix.", title = "Asset API"))
 @Tag(name = "Asset")
 public interface AssetApi {
 
     @Operation(description = "Creates a new asset together with a data address",
-            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = Asset.class))),
+            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = AssetInputSchema.class))),
             responses = {
                     @ApiResponse(responseCode = "200", description = "Asset was created successfully. Returns the asset Id and created timestamp",
-                            content = @Content(schema = @Schema(implementation = IdResponseDto.class))),
+                            content = @Content(schema = @Schema(implementation = ApiCoreSchema.IdResponseSchema.class))),
                     @ApiResponse(responseCode = "400", description = "Request body was malformed",
                             content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
                     @ApiResponse(responseCode = "409", description = "Could not create asset, because an asset with that ID already exists",
@@ -50,10 +53,10 @@ public interface AssetApi {
     JsonObject createAsset(JsonObject asset);
 
     @Operation(description = " all assets according to a particular query",
-            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = QuerySpecDto.class))),
+            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = ApiCoreSchema.QuerySpecSchema.class))),
             responses = {
                     @ApiResponse(responseCode = "200", description = "The assets matching the query",
-                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = AssetResponseDto.class)))),
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = AssetOutputSchema.class)))),
                     @ApiResponse(responseCode = "400", description = "Request body was malformed",
                             content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class))))
             })
@@ -62,7 +65,7 @@ public interface AssetApi {
     @Operation(description = "Gets an asset with the given ID",
             responses = {
                     @ApiResponse(responseCode = "200", description = "The asset",
-                            content = @Content(schema = @Schema(implementation = Asset.class))),
+                            content = @Content(schema = @Schema(implementation = AssetOutputSchema.class))),
                     @ApiResponse(responseCode = "400", description = "Request was malformed, e.g. id was null",
                             content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
                     @ApiResponse(responseCode = "404", description = "An asset with the given ID does not exist",
@@ -87,7 +90,7 @@ public interface AssetApi {
 
     @Operation(description = "Updates an asset with the given ID if it exists. If the asset is not found, no further action is taken. " +
             "DANGER ZONE: Note that updating assets can have unexpected results, especially for contract offers that have been sent out or are ongoing in contract negotiations.",
-            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = AssetUpdateRequestDto.class))),
+            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = AssetInputSchema.class))),
             responses = {
                     @ApiResponse(responseCode = "200", description = "Asset was updated successfully"),
                     @ApiResponse(responseCode = "404", description = "Asset could not be updated, because it does not exist."),
@@ -96,4 +99,67 @@ public interface AssetApi {
             })
     void updateAsset(JsonObject asset);
 
+    @Schema(example = AssetInputSchema.ASSET_INPUT_EXAMPLE)
+    record AssetInputSchema(
+            @Schema(name = ID)
+            String id,
+            @Schema(name = TYPE, example = EDC_ASSET_TYPE)
+            String type,
+            Map<String, Object> properties,
+            Map<String, Object> privateProperties,
+            DataAddressSchema dataAddress
+    ) {
+        public static final String ASSET_INPUT_EXAMPLE = """
+                {
+                    "@context": { "edc": "https://w3id.org/edc/v0.0.1/ns/" },
+                    "@id": "definition-id",
+                    "properties": {
+                        "key": "value"
+                    },
+                    "privateProperties": {
+                        "privateKey": "privateValue"
+                    },
+                    "dataAddress": {
+                        "type": "HttpData"
+                    }
+                }
+                """;
+    }
+
+    @Schema(example = AssetOutputSchema.ASSET_OUTPUT_EXAMPLE)
+    record AssetOutputSchema(
+            @Schema(name = ID)
+            String id,
+            @Schema(name = TYPE, example = EDC_ASSET_TYPE)
+            String type,
+            Map<String, Object> properties,
+            Map<String, Object> privateProperties,
+            DataAddressSchema dataAddress,
+            long createdAt
+    ) {
+        public static final String ASSET_OUTPUT_EXAMPLE = """
+                {
+                    "@context": { "edc": "https://w3id.org/edc/v0.0.1/ns/" },
+                    "@id": "definition-id",
+                    "edc:properties": {
+                        "edc:key": "value"
+                    },
+                    "edc:privateProperties": {
+                        "edc:privateKey": "privateValue"
+                    },
+                    "edc:dataAddress": {
+                        "edc:type": "HttpData"
+                    },
+                    "edc:createdAt": 1688465655
+                }
+                """;
+    }
+
+    record DataAddressSchema(
+            @Schema(name = TYPE, example = DataAddress.EDC_DATA_ADDRESS_TYPE)
+            String type,
+            @Schema(name = "type")
+            String typeProperty
+    ) { }
+
 }