Deprecate /api/v1/tag/{policyUuid} in favor of `/api/v1/tag/policy/…

…{uuid}` The deprecated endpoint is ambiguous. See #586 (comment) Signed-off-by: nscuro <[email protected]>
DependencyTrack · Jun 26, 2024 · d3cffe6 · d3cffe6
1 parent 24e1773
commit d3cffe6
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 11 deletions.
diff --git a/src/main/java/org/dependencytrack/persistence/QueryManager.java b/src/main/java/org/dependencytrack/persistence/QueryManager.java
@@ -1340,8 +1340,8 @@ public List<TagQueryManager.TaggedPolicyRow> getTaggedPolicies(final String tagN
         return getTagQueryManager().getTaggedPolicies(tagName);
     }
 
-    public PaginatedResult getTags(String policyUuid) {
-        return getTagQueryManager().getTags(policyUuid);
+    public PaginatedResult getTagsForPolicy(String policyUuid) {
+        return getTagQueryManager().getTagsForPolicy(policyUuid);
     }
 
     /**

diff --git a/src/main/java/org/dependencytrack/persistence/TagQueryManager.java b/src/main/java/org/dependencytrack/persistence/TagQueryManager.java
@@ -251,7 +251,7 @@ public List<TaggedPolicyRow> getTaggedPolicies(final String tagName) {
     }
 
     @Override
-    public PaginatedResult getTags(String policyUuid) {
+    public PaginatedResult getTagsForPolicy(String policyUuid) {
 
         LOGGER.debug("Retrieving tags under policy " + policyUuid);
 

diff --git a/src/main/java/org/dependencytrack/resources/v1/TagResource.java b/src/main/java/org/dependencytrack/resources/v1/TagResource.java
@@ -157,7 +157,7 @@ public Response getTaggedPolicies(
     }
 
     @GET
-    @Path("/{policyUuid}")
+    @Path("/policy/{uuid}")
     @Produces(MediaType.APPLICATION_JSON)
     @Operation(
             summary = "Returns a list of all tags associated with a given policy",
@@ -174,11 +174,43 @@ public Response getTaggedPolicies(
             @ApiResponse(responseCode = "401", description = "Unauthorized")
     })
     @PermissionRequired(Permissions.Constants.VIEW_PORTFOLIO)
-    public Response getTags(@Parameter(description = "The UUID of the policy", schema = @Schema(type = "string", format = "uuid"), required = true)
-                            @PathParam("policyUuid") @ValidUuid String policyUuid) {
+    public Response getTagsForPolicy(
+            @Parameter(description = "The UUID of the policy", schema = @Schema(type = "string", format = "uuid"), required = true)
+            @PathParam("uuid") @ValidUuid final String uuid
+    ) {
         try (QueryManager qm = new QueryManager(getAlpineRequest())) {
-            final PaginatedResult result = qm.getTags(policyUuid);
+            final PaginatedResult result = qm.getTagsForPolicy(uuid);
             return Response.ok(result.getObjects()).header(TOTAL_COUNT_HEADER, result.getTotal()).build();
         }
     }
+
+    @GET
+    @Path("/{policyUuid}")
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(
+            summary = "Returns a list of all tags associated with a given policy",
+            description = """
+                    <p><strong>Deprecated</strong>. Use <code>/api/v1/tag/policy/{uuid}</code> instead.</p>
+                    <p>Requires permission <strong>VIEW_PORTFOLIO</strong></p>
+                    """
+    )
+    @PaginatedApi
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "A list of all tags associated with a given policy",
+                    headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of tags", schema = @Schema(format = "integer")),
+                    content = @Content(array = @ArraySchema(schema = @Schema(implementation = Tag.class)))
+            ),
+            @ApiResponse(responseCode = "401", description = "Unauthorized")
+    })
+    @PermissionRequired(Permissions.Constants.VIEW_PORTFOLIO)
+    @Deprecated(forRemoval = true)
+    public Response getTags(
+            @Parameter(description = "The UUID of the policy", required = true)
+            @PathParam("policyUuid") final UUID policyUuid
+    ) {
+        return getTagsForPolicy(String.valueOf(policyUuid));
+    }
+
 }
diff --git a/src/test/java/org/dependencytrack/resources/v1/TagResourceTest.java b/src/test/java/org/dependencytrack/resources/v1/TagResourceTest.java
@@ -487,15 +487,15 @@ public void getTaggedPoliciesWithNonLowerCaseTagNameTest() {
     }
 
     @Test
-    public void getAllTagsWithOrderingTest() {
+    public void getTagsForPolicyWithOrderingTest() {
         for (int i = 1; i < 5; i++) {
             qm.createTag("Tag " + i);
         }
         qm.createProject("Project A", null, "1", List.of(qm.getTagByName("Tag 1"), qm.getTagByName("Tag 2")), null, null, true, false);
         qm.createProject("Project B", null, "1", List.of(qm.getTagByName("Tag 2"), qm.getTagByName("Tag 3"), qm.getTagByName("Tag 4")), null, null, true, false);
         Policy policy = qm.createPolicy("Test Policy", Policy.Operator.ANY, Policy.ViolationState.INFO);
 
-        Response response = jersey.target(V1_TAG + "/" + policy.getUuid())
+        Response response = jersey.target(V1_TAG + "/policy/" + policy.getUuid())
                 .request()
                 .header(X_API_KEY, apiKey)
                 .get();
@@ -509,7 +509,7 @@ public void getAllTagsWithOrderingTest() {
     }
 
     @Test
-    public void getTagsWithPolicyProjectsFilterTest() {
+    public void getTagsForPolicyWithPolicyProjectsFilterTest() {
         for (int i = 1; i < 5; i++) {
             qm.createTag("Tag " + i);
         }
@@ -520,7 +520,7 @@ public void getTagsWithPolicyProjectsFilterTest() {
         Policy policy = qm.createPolicy("Test Policy", Policy.Operator.ANY, Policy.ViolationState.INFO);
         policy.setProjects(List.of(qm.getProject("Project A", "1"), qm.getProject("Project C", "1")));
 
-        Response response = jersey.target(V1_TAG + "/" + policy.getUuid())
+        Response response = jersey.target(V1_TAG + "/policy/" + policy.getUuid())
                 .request()
                 .header(X_API_KEY, apiKey)
                 .get();
@@ -532,4 +532,20 @@ public void getTagsWithPolicyProjectsFilterTest() {
         Assert.assertEquals(3, json.size());
         Assert.assertEquals("tag 1", json.getJsonObject(0).getString("name"));
     }
+
+    @Test
+    public void getTagWithNonUuidNameTest() {
+        // NB: This is just to ensure that requests to /api/v1/tag/<value>
+        // are not matched with the deprecated "getTagsForPolicy" endpoint.
+        // Once we implement an endpoint to request individual tags,
+        // this test should fail and adjusted accordingly.
+        qm.createTag("not-a-uuid");
+
+        final Response response = jersey.target(V1_TAG + "/not-a-uuid")
+                .request()
+                .header(X_API_KEY, apiKey)
+                .get();
+        assertThat(response.getStatus()).isEqualTo(404);
+    }
+
 }